jlcpcb-mcp-parts-finder/README.md

MCP server for searching JLCPCB electronic components database

# JLCPCB MCP Parts Finder

A Model Context Protocol (MCP) server for searching the JLCPCB electronic components database in Claude.

## Quick Start

1. Install the package:
   ```bash
   npm install -g jlcpcb-mcp-parts-finder
   ```

2. Download the database (see Database Setup section below)

3. Add to Claude:
   ```bash
   claude mcp add jlcpcb-mcp-parts-finder "npx jlcpcb-mcp-parts-finder"
   ```

4. Restart Claude Code completely

## Installation

### Option 1: Install from npm (Recommended)
```bash
npm install -g jlcpcb-mcp-parts-finder
```

### Option 2: Install from source
```bash
git clone https://github.com/takazudo/jlcpcb-parts-find-mcp.git
cd jlcpcb-parts-find-mcp
npm install
npm run build
npm link
```

## Database Setup

The server requires the JLCPCB database file (`cache.sqlite3`, ~11GB).

### Download the database

1. Visit https://yaqwsx.github.io/jlcparts/
2. Download all database parts:
   - `cache.zip`
   - `cache.z01` through `cache.z18`
3. Combine and extract:
   ```bash
   # Combine all parts
   cat cache.z* > cache_combined.zip
   
   # Extract the database
   unzip cache_combined.zip
   
   # Install to default location
   mkdir -p ~/.jlcpcb-mcp
   mv cache.sqlite3 ~/.jlcpcb-mcp/
   ```

The database will be placed at `~/.jlcpcb-mcp/cache.sqlite3`.

## Claude Configuration

After installing, add the MCP server to Claude:

### For npm installation:
```bash
claude mcp add jlcpcb-mcp-parts-finder "npx jlcpcb-mcp-parts-finder"
```

### For source installation:
```bash
claude mcp add jlcpcb-mcp-parts-finder "node /path/to/jlcpcb-parts-find-mcp/dist/index.js"
```

**Important:** After adding the MCP server, you must completely restart Claude Code for the tools to become available.

## Troubleshooting

### MCP tools not showing up in Claude

If the JLCPCB MCP tools don't appear after installation:

1. **Verify installation:**
   ```bash
   # Check if MCP is listed
   claude mcp list
   
   # Should show:
   # jlcpcb-mcp-parts-finder: npx jlcpcb-mcp-parts-finder
   ```

2. **If not listed, add it again:**
   ```bash
   claude mcp add jlcpcb-mcp-parts-finder "npx jlcpcb-mcp-parts-finder"
   ```

3. **Restart Claude Code completely:**
   - Close all Claude Code windows
   - Wait a few seconds
   - Start Claude Code fresh

4. **Verify database exists:**
   ```bash
   ls ~/.jlcpcb-mcp/cache.sqlite3
   ```

5. **Test the server directly:**
   ```bash
   npx jlcpcb-mcp-parts-finder
   # Should output: "JLCPCB MCP server started"
   # Press Ctrl+C to stop
   ```

**Note:** Sometimes it takes a few minutes for new MCP servers to be recognized by Claude. If the tools still don't appear, try creating a new conversation.

## Usage

Once configured, you can use these commands in Claude:

### List all component categories
```
Use mcp__jlcpcb-mcp-parts-finder__list_categories to find category IDs
```

### Search for parts
```
Use mcp__jlcpcb-mcp-parts-finder__search_parts with:
- category_id: 512 (for PMIC/Regulators)
- keyword: "12V"
- limit: 10
```

## Available Tools

### `search_parts`
Search for components by category and keyword.

**Parameters:**
- `category_id` (number, required) - Category ID from list_categories
- `keyword` (string, optional) - Search term
- `limit` (number, optional) - Max results (default: 20)

### `list_categories`
List all available component categories with their IDs.

## Examples

### Find voltage regulators
1. First, list categories to find the regulator category ID
2. Search for specific parts:
   ```
   category_id: 512
   keyword: "LM7812"
   limit: 5
   ```

### Find audio connectors
```
category_id: 208
keyword: "3.5mm"
limit: 10
```

## Troubleshooting

### Tools not appearing in Claude
- Make sure to restart Claude Code completely (not just create a new session)
- Verify the MCP is configured: `claude mcp list`
- Check if the server responds: `echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx jlcpcb-mcp-parts-finder`

### Database not found
- Ensure the database is at `~/.jlcpcb-mcp/cache.sqlite3`
- Check file permissions
- Set custom path with: `export JLCPCB_DB_PATH=/your/path/cache.sqlite3`

### No search results
- Use `list_categories` first to find the correct category_id
- Try broader keywords
- Some categories may have limited parts

## License

MIT