jlcpcb-search-mcp 1.2.1

MCP server for searching JLCPCB components with live stock and pricing

JLCPCB Search MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with powerful search capabilities for JLCPCB's electronic component catalog. Search 450,000+ components with real-time stock levels and pricing.

Built on top of yaqwsx/jlcparts - huge thanks to Jan Mrazek for doing the hard work of downloading JLCPCB XLS sheets, converting them to structured JSON, and hosting them for the community!

Features

• Fast Local Search: SQLite database with 450K+ components for instant searches
• Live Data: Real-time stock levels and pricing from JLCPCB API
• Smart Filtering: Filter by package type, category, Basic/Extended parts, minimum stock
• Detailed Information: Full specifications, datasheets, pricing tiers, and images
• Easy Integration: Works with Claude Desktop, VSCode, and any MCP-compatible client

Example Usage

Ask Claude natural questions about components:

You: "Can you find a good 10uF SMD capacitor that can support 10V or less?"

Claude's Response:

Based on my search, here are some good 10uF SMD capacitors that can support 10V or less:

Recommended Options (Aluminum Electrolytic SMD):

Best Choice - C4747968 (RST10UF16V013)

• Rating: 10uF, 16V
• Package: SMD, D4xL5.4mm
• Stock: 76,080 units (excellent availability)
• Price: $0.0248 (20+), $0.0170 (600+)
• Link: https://jlcpcb.com/partdetail/C4747968

Alternative - C970654 (RVT1C100M0405)

• Rating: 10uF, 16V
• Package: SMD, D4xL5.4mm
• Stock: 7,360 units
• Price: $0.0293 (20+), $0.0202 (600+)
• Link: https://jlcpcb.com/partdetail/C970654

All of these are aluminum electrolytic SMD capacitors rated for 16V, which gives you plenty of margin for a 10V application. The C4747968 is my top recommendation due to its excellent stock levels and lower price.

Note: These are all Extended parts (not Basic), so they will incur additional assembly fees if you're using JLCPCB assembly.

Tools

The MCP server exposes four tools to your AI assistant:

Tool	What it does
search_components	Keyword search across the catalog. Optional filters: category, package, basic_only, min_stock, max_results.
get_component_details	Full live details for an LCSC part — current stock, pricing tiers, full parameter list, datasheet, and images.
database_status	Reports the local database location, size, and component count.
refresh_database	Re-downloads the catalog snapshot from inside the chat — no CLI needed.

Most of the time you don't call these directly; you ask Claude in natural language ("find me a 10k 0805 resistor with at least 5k in stock") and it picks the right tool.

Data Freshness

This server uses a hybrid approach — a local catalog snapshot for fast search, plus live API calls for stock and pricing.

Data	Source	Freshness
Component catalog (descriptions, packages, attributes, categories)	Local SQLite, built from yaqwsx/jlcparts	Snapshot from your last refresh
Stock levels	Live JLCPCB API (wmsc.lcsc.com)	Real-time, per query
Pricing tiers	Live JLCPCB API	Real-time, per query
Datasheet URL	Live JLCPCB API	Real-time, per query

The local catalog does not auto-update. Refresh it periodically to pick up newly-added parts, removed parts, and metadata changes:

jlcpcb-mcp-setup --refresh-db

For most workflows, refreshing weekly or monthly is sufficient. Stock and price decisions are always made against live data, so you don't need a fresh catalog to trust the numbers on parts you already know.

Installation

From PyPI

# Install for current user (recommended for Claude Desktop)
pip install --user jlcpcb-search-mcp

# Or use pipx for isolated installation (best for CLI tools)
pipx install jlcpcb-search-mcp

# Or install in a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install jlcpcb-search-mcp

# Or install with uv in a project (uv is my fav!)
uv add jlcpcb-search-mcp

From Source

git clone https://github.com/peterb154/jlcpcb-search-mcp.git
cd jlcpcb-search-mcp
pip install -e .

Important: When using Claude Code, the MCP server must be accessible from your project's environment:

• For uv projects: Install with uv add jlcpcb-search-mcp and use uv run claude commands
• For system-wide use: Install with pip install --user jlcpcb-search-mcp or pipx install jlcpcb-search-mcp
• For venv projects: Install in your venv and activate it before starting your editor

Quick Start

Claude Code Configuration

Option 1: Automatic Setup (Recommended)

Use the setup utility to automatically configure the MCP server:

# For current workspace (creates .mcp.json)
# Uses shared database in user's application data directory - RECOMMENDED
jlcpcb-mcp-setup --workspace

# Or if using uv project
uv run jlcpcb-mcp-setup --workspace

# For development of THIS package only (uses ./data/ directory)
# This creates a separate 900MB+ database in your project - avoid unless needed
jlcpcb-mcp-setup --workspace --dev

# Globally for Claude Desktop (also uses shared database)
jlcpcb-mcp-setup --global

After running the setup:

1. Reload your editor window (Cmd+Shift+P → Developer: Reload Window)

2. Check that the MCP server is connected:

   # If using uv project:
   uv run claude mcp list
   

   should return something like the following - notice that the mcp server is connected:

   Checking MCP server health...
   
   jlcpcb-search: jlcpcb-mcp  - ✓ Connected
   

   # Otherwise if not using uv:
   claude mcp list
   

3. You should see: jlcpcb-search: jlcpcb-mcp - ✓ Connected

4. Start searching for components!

Option 2: Manual Configuration

Create .mcp.json in your workspace root:

{
  "mcpServers": {
    "jlcpcb-search": {
      "command": "jlcpcb-mcp"
    }
  }
}

Or for global configuration in Claude Desktop:

macOS: ~/Library/Application Support/Claude/mcp.json Windows: %APPDATA%\Claude\mcp.json Linux: ~/.config/claude/mcp.json

Note for uv projects: The same simple config works! When you run uv run claude, it automatically uses the environment where jlcpcb-mcp is installed. No special configuration needed.

First Run & Database Setup

The database will be automatically built on your first component search. However, you can pre-download it to avoid waiting:

# Pre-download the database (recommended)
jlcpcb-mcp-setup --refresh-db

# Or with uv
uv run jlcpcb-mcp-setup --refresh-db

What to expect:

• Download: ~50MB compressed (manifest + attributes lookup table + ~1,294 per-subcategory shards)
• Final size: ~1.8GB SQLite database uncompressed (~576k components, 1,289 subcategories)
• Time: ~4 minutes on fast internet connection (500Mbps), up to 10 minutes on slower connections
• Progress: Real-time updates showing download progress and subcategory processing

If you don't pre-download, your first Claude query will trigger the download automatically, so expect a 3-10 minute wait.

Database Location

The database is shared across all your projects by default (recommended):

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

Why shared?

• One ~1.8GB database serves all your projects
• Saves disk space
• Faster setup for new projects
• Easier to keep updated

Dev mode (--dev): Only use this if you're developing the jlcpcb-mcp package itself. It creates a separate database in ./data/ which is useful for testing but wastes space for normal usage.

Custom location (JLCPCB_DATABASE_PATH)

If you want the database to live somewhere specific — e.g. an external SSD, a project-local directory, or a path you can .gitignore — set the JLCPCB_DATABASE_PATH environment variable. The value is the full path to the SQLite file (not just the directory):

// .mcp.json (or your client's MCP config)
{
  "mcpServers": {
    "jlcpcb-search": {
      "command": "jlcpcb-mcp",
      "env": {
        "JLCPCB_DATABASE_PATH": "/path/to/your/components.sqlite"
      }
    }
  }
}

To pre-download into that location, export the same variable before running setup:

JLCPCB_DATABASE_PATH=/path/to/your/components.sqlite \
  jlcpcb-mcp-setup --refresh-db

Or skip pre-downloading and let the server build it on the first query.

JLCPCB_DATABASE_PATH takes precedence over both the default platform location and --dev mode.

License

MIT License - see LICENSE file for details

Acknowledgments

• yaqwsx/jlcparts by Jan Mrazek - Component data source and inspiration
• JLC Parts Web Search - If you want a great search UI without AI
• FastMCP - MCP server framework
• JLCPCB - Component data and API

Support

• Issues: GitHub Issues
• Documentation: docs/
• MCP Protocol: Model Context Protocol