jlcpcb-search-mcp 1.0.2

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 Mrázek 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

Installation

From PyPI (Coming Soon)

pip install jlcpcb-mcp

From Source

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

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)
jlcpcb-mcp-setup --workspace

# For development with local database
jlcpcb-mcp-setup --workspace --dev

# Globally for Claude Desktop
jlcpcb-mcp-setup --global

After running the setup:

1. Reload your editor window (Cmd+Shift+P → Developer: Reload Window)
2. The jlcpcb-search MCP server should now be connected
3. Start searching for components!

Option 2: Manual Configuration

Create .mcp.json in your workspace root:

{
  "mcpServers": {
    "jlcpcb-search": {
      "command": "python",
      "args": ["-m", "jlcpcb_mcp.server"]
    }
  }
}

Or for global configuration in Claude Desktop:

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

First Run

On first run, the server will automatically download and build the component database (~50MB compressed, ~900MB uncompressed). This takes 5-10 minutes but only happens once.

The database is stored in:

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

Usage Examples

Once configured, you can ask Claude to search for components:

Basic Search

"Find me a 10k� resistor in 0805 package"

## Search Results for '10k resistor'

Found 1 components

### 1. C17724 - 0805W8F510KT5E

- **Type**: **Basic**
- **Manufacturer**: Uniroyal Elec
- **Package**: 0805
- **Category**: Resistors / Chip Resistor - Surface Mount
- **Stock**: 145,230 units
- **Pricing**:
  - 100+: $0.0008
  - 1,000+: $0.0006
  - 5,000+: $0.0005
- **Datasheet**: https://datasheet.lcsc.com/...
- **JLCPCB Link**: https://jlcpcb.com/partdetail/C17724

Detailed Component Info

"Get full details for component C17976"

Returns complete specifications, all pricing tiers, parameters, datasheet links, and component images.

Advanced Filtering

"Find STM32 microcontrollers with at least 1000 units in stock"

"Show me basic ceramic capacitors in 0603 package"

Available MCP Tools

search_components

Search for components by keyword with optional filters.

Parameters:

• query (string): Search keywords (e.g., "10k resistor", "STM32F4")
• category (string, optional): Filter by category
• package (string, optional): Filter by package (e.g., "0805", "QFN-32")
• basic_only (boolean, optional): Only show Basic parts (default: false)
• min_stock (integer, optional): Minimum stock level
• max_results (integer): Maximum results to return (default: 10, max: 50)

Returns: Formatted list of components with live stock and pricing

get_component_details

Get detailed information for a specific component.

Parameters:

• lcsc (string): JLCPCB part number (e.g., "C17976")

Returns: Comprehensive component details including:

• Full specifications
• Current stock and all pricing tiers
• Datasheet and image links
• Package and manufacturer info
• Category classification

Development

Setup Development Environment

# Clone repository
git clone https://github.com/yourusername/jlcpcb-search-mcp.git
cd jlcpcb-search-mcp

# Install dependencies
pip install -e ".[dev]"

# Enable dev mode (uses ./data directory)
export JLCPCB_DEV_MODE=1

Testing

# Test database download and queries
JLCPCB_DEV_MODE=1 python test_db.py

# Test MCP server tools
JLCPCB_DEV_MODE=1 python test_server.py

Project Structure

jlcpcb-search-mcp/
\x00\x00 src/
   \x00\x00 jlcpcb_mcp/
       \x00\x00 __init__.py
       \x00\x00 database.py      # Database manager
       \x00\x00 server.py         # MCP server and tools
\x00\x00 docs/
   \x00\x00 data-sources.md       # Data source documentation
\x00\x00 test_db.py                # Database tests
\x00\x00 test_server.py            # Server tests
\x00\x00 pyproject.toml
\x00\x00 README.md

How It Works

Hybrid Data Approach

1. Local Catalog: SQLite database with component specs, categories, packages

   • Downloaded from yaqwsx/jlcparts
   • Updated weekly/monthly
   • Fast parametric searches

2. Live API: Real-time data for critical information

   • Current stock levels
   • Latest pricing tiers
   • Availability status

This hybrid approach provides:

• Fast searches (local SQLite)
• Fresh stock/pricing (JLCPCB API)
• Works offline (with cached data)

Database Updates

The database can be manually updated:

from jlcpcb_mcp.database import DatabaseManager

db = DatabaseManager()
db.update_database()  # Re-download latest data

Data Sources

• Component Catalog: yaqwsx/jlcparts (pre-processed JSON)
• Live Stock/Pricing: JLCPCB API (wmsc.lcsc.com)
• Component Specs: Extracted from JLCPCB's XLS exports

See docs/data-sources.md for detailed information about data sources and backup strategies.

Basic vs Extended Parts

JLCPCB categorizes components as:

• Basic Parts: No additional assembly fees, optimized inventory
• Extended Parts: Small additional fee ($0.002-0.005 per component)
• Preferred Parts: Extended parts with high inventory

This tool clearly indicates part type in all search results.

API Rate Limiting

The JLCPCB API has no official rate limits, but best practices:

• Results are enhanced with live data on-demand
• API calls include proper headers (User-Agent, Referer)
• Graceful degradation if API is unavailable
• Future: Optional caching layer (5-15 min TTL)

Contributing

Contributions welcome! Areas for improvement:

• Add more MCP tools (search by specs, find alternatives, compare components)
• Implement response caching
• Add parametric search by electrical properties
• Support for other component distributors

License

MIT License - see LICENSE file for details

Alternative: JLC Parts Web Search

If you just want a better search interface for JLCPCB components (without AI integration), check out JLC Parts by Jan Mrázek.

It's an excellent web-based search tool with:

• Fast parametric search
• Advanced filtering
• Component comparisons
• Direct KiCad integration

This MCP server uses their pre-processed component data - huge thanks to Jan and contributors for maintaining that project!

Acknowledgments

• yaqwsx/jlcparts by Jan Mrázek - 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