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