Metadata-Version: 2.4
Name: jlcpcb-search-mcp
Version: 1.2.0
Summary: MCP server for searching JLCPCB components with live stock and pricing
Project-URL: Homepage, https://github.com/peterb154/jlcpcb-search-mcp
Project-URL: Repository, https://github.com/peterb154/jlcpcb-search-mcp
Author-email: Brian Peterson <brian.peterson@cloudshift.cc>
Requires-Python: >=3.12
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

[![PyPI version](https://badge.fury.io/py/jlcpcb-search-mcp.svg)](https://pypi.org/project/jlcpcb-search-mcp/)

> Built on top of [yaqwsx/jlcparts](https://github.com/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](https://github.com/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:

```bash
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

```bash
# 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

```bash
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:

```bash
# 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:

   ```bash
   # If using uv project:
   uv run claude mcp list
   ```

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

   ```text
   Checking MCP server health...

   jlcpcb-search: jlcpcb-mcp  - ✓ Connected
   ```

   ```bash
   # 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:

```json
{
  "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:

```bash
# 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 900MB 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.

## License

MIT License - see LICENSE file for details

## Acknowledgments

- **[yaqwsx/jlcparts](https://github.com/yaqwsx/jlcparts)** by Jan Mrazek - Component data source and inspiration
- **[JLC Parts Web Search](https://yaqwsx.github.io/jlcparts/#/)** - If you want a great search UI without AI
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- JLCPCB - Component data and API

## Support

- **Issues**: [GitHub Issues](https://github.com/peterb154/jlcpcb-search-mcp/issues)
- **Documentation**: [docs/](docs/)
- **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io/)
