jlcpcb-mcp

An MCP server for JLCPCB / LCSC components. Search the parts catalog and pull live stock, pricing tiers, datasheets, specifications, and images — straight into Claude, Cursor, or any MCP client.

It uses a hybrid data model:

| Data | Source | Freshness | |---|---|---| | Component catalog (descriptions, packages, attributes, categories) | Local SQLite, built from yaqwsx/jlcparts | Snapshot from your last refresh | | JLCPCB assembly stock (the figure that matters for PCBA) | Catalog snapshot (or the official Parts API, when authorized) | Snapshot / real-time | | LCSC retail stock | Live LCSC API (wmsc.lcsc.com) | Real-time, per query | | Pricing tiers | Live LCSC API (wmsc.lcsc.com) | Real-time, per query | | Datasheet URL | Live LCSC API (wmsc.lcsc.com) | Real-time, per query |

Two stock pools, don't confuse them. wmsc.lcsc.com reports LCSC retail stock, which is a different inventory from JLCPCB assembly stock. A part can read 0 on LCSC retail while having millions available for JLC assembly (common for Basic parts). Tools expose both as lcsc_retail_stock and jlc_assembly_stock; treat assembly stock as authoritative for board production. The official Parts API (getComponentDetailByCode) gives real-time assembly stock once your API access is approved.

The catalog is downloaded and built into a local SQLite database on first use (a one-time download of ~50 MB that expands to a larger on-disk database). Stock, pricing, and datasheet links are always fetched live, so they're current regardless of catalog age. No API key or account is required.

Tools

Catalog + live data (no credentials needed)

| Tool | Description | |---|---| | jlcpcb_search_components | Search the catalog by keyword + filters (category, package, basic-only, min stock) and parametric values (resistance, capacitance, voltage rating, power, output voltage/current, input voltage). Results are enriched with live stock/pricing and ranked Basic-first, then by stock, then by price. | | jlcpcb_get_component_details | Full details for one part: catalog metadata + live stock, full pricing tiers, specifications, datasheet, and images. | | jlcpcb_get_component_stock | Live, real-time stock quantity for a part (falls back to the catalog snapshot). | | jlcpcb_get_component_pricing | Live quantity-break pricing tiers (USD) for a part. | | jlcpcb_get_datasheet_url | Datasheet PDF URL for a part (live, with catalog fallback). | | jlcpcb_list_categories | List catalog categories/subcategories with component counts. | | jlcpcb_database_status | Report the local catalog DB location, size, component count, and last build time. | | jlcpcb_refresh_database | Rebuild the local catalog from the latest yaqwsx/jlcparts snapshot. |

Official JLCPCB Open API (requires credentials)

These call the authenticated JLCPCB Open API (open.jlcpcb.com, HMAC-SHA256 signed). They return a "not configured" message until you set the credentials below. Apply for access at https://api.jlcpcb.com (approval is based on your order history).

| Tool | Description | |---|---| | jlcpcb_official_get_component_detail | Authoritative details (specs/stock/price/attributes) for one or more LCSC codes. | | jlcpcb_official_component_library | Browse the full assembly component library, paginated. | | jlcpcb_official_private_library | List your account's private/consigned component library. | | jlcpcb_official_component_feed | Cursor-paginated bulk feed of the whole catalog (lastKey). |

PCB / SMT-stencil ordering (requires credentials)

| Tool | Description | |---|---| | jlcpcb_pcb_upload_gerber | Upload a Gerber archive; returns a fileKey. | | jlcpcb_pcb_upload_blind_via_hole_img | Upload a blind/buried-via stackup image. | | jlcpcb_pcb_impedance_template_list | List impedance template settings for a stackup. | | jlcpcb_pcb_stencil_price_config | Get the SMT stencil (steel) price configuration. | | jlcpcb_pcb_calculate_price | Quote price + lead time for a PCB / stencil order (no order placed). | | jlcpcb_pcb_get_order_detail | Order details by batch number. | | jlcpcb_pcb_get_audit_info | Engineering audit (review) info for an uploaded design. | | jlcpcb_pcb_get_wip_process | Work-in-progress production status for an order. | | jlcpcb_pcb_create_order ⚠️ | Place a real, paid PCB order. Gated by JLCPCB_ENABLE_ORDERS. |

3D printing (TDP) (requires credentials)

| Tool | Description | |---|---| | jlcpcb_tdp_upload_model | Upload a 3D model (STL/STEP); returns a fileAccessId. | | jlcpcb_tdp_file_analysis_result | Analysis result (dimensions/printability) for an uploaded model. | | jlcpcb_tdp_calculate_price | Quote price for a 3D-printing job (no order placed). | | jlcpcb_tdp_order_list | List your 3D-printing orders (paginated/filterable). | | jlcpcb_tdp_order_detail | 3D-printing order details by batch number. | | jlcpcb_tdp_order_process | Production progress for a 3D-printing order. | | jlcpcb_tdp_create_order ⚠️ | Place a real, paid 3D-printing order. Gated by JLCPCB_ENABLE_ORDERS. |

Order safety: the two *_create_order tools place real, paid orders and are disabled by default. They only work when JLCPCB_ENABLE_ORDERS=true and credentials are set. Uploads and price quotes are free and need only credentials.

Installation

The server runs over stdio and is launched by your MCP client.

Claude Desktop / generic MCP config

{
  "mcpServers": {
    "jlcpcb": {
      "command": "npx",
      "args": ["-y", "jlcpcb-mcp"]
    }
  }
}

Claude Code

claude mcp add jlcpcb -- npx -y jlcpcb-mcp

Install globally

npm install -g jlcpcb-mcp
jlcpcb-mcp   # runs the stdio server

First run builds the local catalog database (one-time, a few minutes). Subsequent queries are instant. Use the jlcpcb_refresh_database tool to update the catalog later.

Configuration

All configuration is optional — the live API needs no credentials.

| Env var | Purpose | |---|---| | JLCPCB_DATABASE_PATH | Override where the catalog SQLite file is stored. | | JLCPCB_DEV_MODE | Store the database in ./data within the project (for development). | | JLCPCB_APP_ID / JLCPCB_ACCESS_KEY / JLCPCB_SECRET_KEY | Official Open API credentials — enable the jlcpcb_official_* tools. | | JLCPCB_ENDPOINT | Override the official API base (default https://open.jlcpcb.com). | | JLCPCB_ENABLE_ORDERS | Set to true/1 to allow the *_create_order tools to place real paid orders (off by default). |

Default database locations:

• Windows: %LOCALAPPDATA%\jlcpcb-mcp\components.sqlite
• macOS: ~/Library/Application Support/jlcpcb-mcp/components.sqlite
• Linux: ~/.local/share/jlcpcb-mcp/components.sqlite

Development

npm install
npm run build      # tsc -> dist/
npm test           # vitest (mocks network + DB; no large download)
npm run test:watch
npm run dev        # ts-node src/index.ts

The test suite mocks the live API and the catalog download, so it runs fast and offline.

Architecture

src/
  index.ts          # registers all tools on the MCP server (stdio)
  tool.ts           # shared ToolDef type
  live-client.ts    # wmsc.lcsc.com live product API client
  official-client.ts# open.jlcpcb.com authenticated API (HMAC-SHA256 signing)
  database.ts       # DatabaseManager: build/verify/query the catalog (better-sqlite3)
  paths.ts          # platform data-dir resolution
  value-parser.ts   # resistance/capacitance/voltage/current/power parsers
  tools/
    search.ts       # jlcpcb_search_components
    details.ts      # get_component_details / _stock / _pricing / _datasheet
    catalog.ts      # jlcpcb_list_categories
    maintenance.ts  # jlcpcb_database_status / jlcpcb_refresh_database
    official.ts     # jlcpcb_official_* (authenticated Parts API)
    pcb.ts          # jlcpcb_pcb_* (PCB/SMT-stencil quote, upload, order)
    tdp.ts          # jlcpcb_tdp_* (3D-printing quote, upload, order)

Releasing

CI runs the build + tests on every push and PR to main (Node 20 & 22). Publishing is triggered by creating a GitHub Release, which publishes to both registries:

• npm as the unscoped package jlcpcb-mcp
• GitHub Packages as @eyalm321/jlcpcb-mcp

One-time repo setup

1. Push this repo to https://github.com/Eyalm321/jlcpcb-mcp.
2. Add an NPM_TOKEN repository secret (an npm automation token). GITHUB_TOKEN is provided automatically for GitHub Packages.
3. To release: bump the version in package.json, commit, then create a GitHub Release (tag e.g. v0.1.0). The publish workflow builds, tests, and publishes to both registries.

Credits

• Catalog data: yaqwsx/jlcparts
• Architecture inspired by peterb154/jlcpcb-search-mcp
• Catalog facts originate from JLCPCB / LCSC and are subject to their terms.

License

MIT © Eyalm321