How do I use jlcpcb-search-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@jlcpcb-search-mcp find a 10k 0805 resistor with at least 5k in stock" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

jlcpcb-search-mcp

by peterb154

Overview Schema Source Related Servers Discussions Admin

Python

Local

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

Related MCP server: Nexar MCP Server

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:

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

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

You should see: jlcpcb-search: jlcpcb-mcp - ✓ Connected
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

Available Tools

4 tools

database_statusA

Get status and information about the local component database.

Returns information including database location, size, age, and last update time.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description outlines the kind of information returned (location, size, age, last update time) and implies a read-only operation. No annotations are provided, but the description sufficiently conveys the tool's behavior for a simple getter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no waste. The first sentence states the main purpose, and the second lists example return fields. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and no parameters, the description is sufficient. It lists typical return fields (location, size, age, last update time), providing useful context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and the input schema is empty with 100% coverage. The description does not need to explain parameter semantics, and it adds no extra parameter info, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'status and information about the local component database'. It effectively distinguishes from siblings: get_component_details (component-level), refresh_database (mutative), search_components (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly guide when to use this tool versus its siblings. While the purpose suggests it is for database-level status checks, it lacks direct contrast or usage conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_component_detailsA

Get detailed information for a specific JLCPCB component.

This tool fetches comprehensive details including specifications, current stock, pricing tiers, datasheet, and images.

Example: lcsc="C17976" returns full details for that specific component.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Parameters for getting detailed component information.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so description carries full burden. It explicitly lists the types of data returned (specifications, stock, pricing, datasheet, images), which gives good insight into behavior. It does not mention any side effects, but as a read-only fetch tool, that is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences plus an example line. The purpose is front-loaded, and every sentence adds value without redundancy. Perfectly sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, clear output via description), and the existence of an output schema (implied), the description covers the essential aspects: what it does, how to use it, and what data it returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% description coverage with a clear description of the 'lcsc' parameter. The description adds value by providing an example and clarifying that it is a JLCPCB part number, going beyond the schema's basic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Get detailed information for a specific JLCPCB component' with a specific verb and resource. It distinguishes itself from sibling tools like search_components (searching vs. fetching a single component) and database_status/refresh_database (management operations).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an example showing how to use the tool (lcsc='C17976') and implies usage context: when you need detailed data for a known component. However, it does not explicitly state when not to use or mention alternatives like search_components for broader queries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

refresh_databaseA

Refresh/update the component database to get the latest parts from JLCPCB.

This downloads the latest component data (~50MB) and rebuilds the local database. Takes 5-10 minutes. Use this monthly to stay current with new components.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool downloads ~50MB, takes 5-10 minutes, and rebuilds the database. It does not mention authentication, concurrency safety, or whether the operation is destructive, but the major behavioral traits are covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, then details and usage frequency. No unnecessary words, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and an output schema (though not shown), the description covers the main aspects: action, size, time, and frequency. Could mention interrupt safety or backup behavior for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4. The description explains the tool's action without needing parameter details. It adds context beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it refreshes the component database to get latest parts from JLCPCB. It distinguishes from sibling tools (database_status, get_component_details, search_components) which are query or read-only tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description recommends monthly use to stay current with new components. It does not explicitly state when not to use or provide alternatives, but the frequency guidance is helpful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_componentsA

Search JLCPCB components by keyword with live stock and pricing.

This tool searches the local component database and enhances results with real-time stock levels and pricing from JLCPCB's API.

Examples:

"10k resistor 0805" - Find 10kΩ resistors in 0805 package
"STM32F4" - Find STM32F4 microcontrollers
"capacitor ceramic 10uF" - Find 10µF ceramic capacitors

Results include:

JLCPCB part number and manufacturer part number
Current stock levels and pricing tiers
Package type and specifications
Basic vs Extended part classification
Direct link to JLCPCB product page

ParametersJSON Schema

Name	Required	Description	Default
`search`	Yes	Parameters for component search.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full burden. It discloses the search behavior (local DB + live API) and result fields, but omits details like sorting, pagination, rate limits, or potential caching of pricing. Adequate but could be more transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with no wasted sentences. It front-loads the purpose, then provides examples and result highlights in a structured list. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the schema covers all parameters and the description explains result fields, the tool is well-documented. However, it lacks mention of pagination or sorting behavior. Overall complete for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for all parameters. The description adds no new semantic detail beyond the schema examples, so baseline is 3. It does not compensate further.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a clear verb-object 'Search JLCPCB components by keyword with live stock and pricing', and provides examples and result fields. It effectively distinguishes itself from siblings like database_status and get_component_details by focusing on search with live data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (searching for components with live availability) and distinguishes from siblings via context. However, it does not explicitly state when not to use it or mention alternatives like get_component_details for specific parts.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv1.2.1Jul 6, 2026
- First observeddatabase_status
- First observedget_component_details
- First observedrefresh_database
- First observedsearch_components

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-07-06 08:40 across 4 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: database status, component details retrieval, database refresh, and keyword search. No overlap in functionality.

Naming Consistency5/5

All tool names use snake_case and consistently follow a verb_noun pattern (e.g., search_components, get_component_details). This provides a predictable naming convention.

Tool Count5/5

With 4 tools, the set is well-scoped for a component search server, covering core operations without being too sparse or excessive.

Completeness4/5

The tool set covers the primary workflow: searching, getting details, refreshing data, and checking database health. Minor omission like category browsing but core functionality is complete.

Maintenance

ActivityNo data

ResponsivenessResponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

sheetsdata-mcp A
io.github.octoco-ltd
Electronic component datasheets for AI agents — specs, pinouts, package data on demand.
Embedded system Developer Tools Research & Data
12211
catalog A
ai.partsgraph
Search real parts with datasheet-provenance specs, check compatibility and compose priced BOMs.
Search E-commerce & Retail
111
Source PartsOAuth
io.github.SourceParts
Electronic component sourcing, BOM management, and PCB design workflows.
Developer Tools App Automation Product Management
21
partreel A
io.github.mingyo186
Verified KiCad footprints, symbols & 3D models for AI agents. No signup, CC-BY-4.0, quality-gated.
Embedded system Developer Tools
72

Related MCP Servers

tscircuit MCP Server
charlielockyer-rice
A
license
Not graded
quality
D
maintenance
Provides Claude with access to the tscircuit electronics component registry, enabling search, browsing, and analysis of electronic components and circuit packages from the tscircuit ecosystem.
Updated a year ago (2025-07-09 21:42 UTC)
3
MIT
Nexar MCP Server
Search E-commerce & Retail Research & Data
phuhduong
A
license
Not graded
quality
Not graded
maintenance
Enables searching for electronic components through the Nexar Supply API, providing detailed part information including manufacturer, pricing, specifications, and datasheets.
Updated 10 months ago (2025-11-09 11:55 UTC)
-
Nexar MCP Server
E-commerce & Retail Search Developer Tools
Farad-Labs
F
license
Not graded
quality
C
maintenance
Enables searching for electronic components, comparing prices across distributors, checking availability, and retrieving datasheets through the Nexar/Octopart API with specialized tools for resistors, capacitors, inductors, semiconductors, crystals, and connectors.
Updated 9 months ago (2025-12-13 19:33 UTC)
8
-
PCB Parts MCP Server
Developer Tools Search
Averyy
A
license
A
quality
A
maintenance
Enables searching and filtering over 1.5 million electronic components across JLCPCB, Mouser, and DigiKey using parametric queries and smart parsing. It supports finding alternative parts, accessing pinout data, and downloading KiCad footprints directly through AI coding assistants.
Updated 2 days ago (2026-09-13 16:40 UTC)
11
112
MIT

JLCPCB Search MCP Server

Features

Example Usage

Best Choice - C4747968 (RST10UF16V013)

Alternative - C970654 (RVT1C100M0405)

Tools

Data Freshness

Installation

From PyPI

From Source

Quick Start

Claude Code Configuration

Option 1: Automatic Setup (Recommended)

Option 2: Manual Configuration

First Run & Database Setup

Database Location

Custom location (JLCPCB_DATABASE_PATH)

License

Acknowledgments

Support

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Custom location (`JLCPCB_DATABASE_PATH`)