digikey-mcp

# DigiKey MCP Server A [Model Context Protocol](https://modelcontextprotocol.io/) server for the DigiKey Product Search API v4, built with [FastMCP](https://github.com/jlowin/fastmcp). Docker-first, designed for the [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/). Originally inspired by [bengineer19/digikey_mcp](https://github.com/bengineer19/digikey_mcp). ## Prerequisites - **DigiKey API credentials** — Register at [developer.digikey.com](https://developer.digikey.com/), create an app with `client_credentials` grant type - **DigiKey Customer Number** — Required for order tools. Find it in your [DigiKey account settings](https://www.digikey.com/account/myaccount/). - **Docker** (recommended) or Python 3.10+ - **Docker MCP Toolkit** — included with [Docker Desktop](https://www.docker.com/products/docker-desktop/) (requires MCP Toolkit support) ## Project Structure ``` digikey-mcp/ ├── mcp_app.py # Shared FastMCP instance ├── digikey_mcp_server.py # Main server — authenticated tools (OAuth2) ├── digikey_noauth_tools.py # No-auth tools (cart URL, MyList link) ├── Dockerfile # Docker image with embedded metadata ├── server.yaml # Registry entry for docker/mcp-registry └── tests/ # Unit tests ``` ## Quick Start — Docker MCP Toolkit The recommended way to run this server. The Docker MCP gateway manages the container lifecycle, injects secrets, and exposes tools to MCP clients like Claude Code or Claude Desktop. ### 1. Build the Docker image ```bash git clone https://github.com/simon-77/digikey-mcp.git cd digikey-mcp docker build -t digikey-mcp:latest . ``` ### 2. Create a custom catalog The gateway discovers servers through catalog files. Create one at `~/.docker/mcp/catalogs/custom.yaml`: ```yaml version: 3 name: custom displayName: Custom MCP Servers registry: digikey: description: DigiKey component search, pricing, ordering, and order status title: DigiKey type: server image: digikey-mcp:latest secrets: - name: digikey.CLIENT_ID env: CLIENT_ID - name: digikey.CLIENT_SECRET env: CLIENT_SECRET - name: digikey.DIGIKEY_ACCOUNT_ID env: DIGIKEY_ACCOUNT_ID env: - name: USE_SANDBOX value: "false" - name: DIGIKEY_LOCALE_SITE value: "US" - name: DIGIKEY_LOCALE_LANGUAGE value: "en" - name: DIGIKEY_LOCALE_CURRENCY value: "USD" tools: - name: keyword_search - name: product_details - name: search_manufacturers - name: search_categories - name: get_category_by_id - name: search_product_substitutions - name: get_product_media - name: get_product_pricing - name: get_digi_reel_pricing - name: generate_cart_url - name: create_mylist_link - name: list_orders - name: get_order_status prompts: 0 resources: {} ``` Change the `env` values to match your locale (e.g., `AT`/`en`/`EUR` for Austria). > **Note:** The `tools` list must match the tools defined in the server. The gateway uses this list to register tools with MCP clients. `prompts: 0` and `resources: {}` indicate the server exposes no MCP prompts or resources. ### 3. Register the catalog and enable the server ```bash docker mcp catalog import ~/.docker/mcp/catalogs/custom.yaml docker mcp server enable digikey ``` Re-run `catalog import` whenever you modify `custom.yaml`. ### 4. Set secrets ```bash docker mcp secret set digikey.CLIENT_ID docker mcp secret set digikey.CLIENT_SECRET docker mcp secret set digikey.DIGIKEY_ACCOUNT_ID ``` You'll be prompted to enter each value. Secret names **must** be prefixed with the server name (`digikey.`). The Account ID is your DigiKey customer number — required for order tools (`list_orders`, `get_order_status`). ### 5. Connect an MCP client ```bash docker mcp client connect claude-code ``` This adds the gateway to your project's `.mcp.json`: ```json { "mcpServers": { "MCP_DOCKER": { "command": "docker", "args": ["mcp", "gateway", "run"], "type": "stdio" } } } ``` When the MCP client starts, the gateway launches the `digikey-mcp:latest` container, injects secrets as environment variables, and proxies tool calls. ### Rebuilding after changes ```bash docker build -t digikey-mcp:latest . # Restart your MCP client to pick up the new image ``` No need to re-import the catalog or re-set secrets — just rebuild and restart. ## Alternative: Docker standalone Run the container directly without the MCP Toolkit. You manage secrets and lifecycle yourself. ```bash docker build -t digikey-mcp . docker run --rm -i \ -e CLIENT_ID=your_client_id \ -e CLIENT_SECRET=your_client_secret \ -e DIGIKEY_ACCOUNT_ID=your_customer_number \ -e USE_SANDBOX=false \ -e DIGIKEY_LOCALE_SITE=US \ -e DIGIKEY_LOCALE_LANGUAGE=en \ -e DIGIKEY_LOCALE_CURRENCY=USD \ digikey-mcp ``` `.mcp.json` for MCP clients: ```json { "mcpServers": { "digikey": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CLIENT_ID=your_client_id", "-e", "CLIENT_SECRET=your_client_secret", "-e", "DIGIKEY_ACCOUNT_ID=your_customer_number", "-e", "USE_SANDBOX=false", "-e", "DIGIKEY_LOCALE_SITE=US", "-e", "DIGIKEY_LOCALE_LANGUAGE=en", "-e", "DIGIKEY_LOCALE_CURRENCY=USD", "digikey-mcp" ] } } } ``` Locale env vars are optional — defaults are `US`/`en`/`USD` (see [Configuration](#configuration)). ## Alternative: Standalone (pip) Run without Docker. Requires Python 3.10+. ```bash git clone https://github.com/simon-77/digikey-mcp.git cd digikey-mcp pip install . cat > .env <<EOF CLIENT_ID=your_client_id CLIENT_SECRET=your_client_secret DIGIKEY_ACCOUNT_ID=your_customer_number USE_SANDBOX=false DIGIKEY_LOCALE_SITE=US DIGIKEY_LOCALE_LANGUAGE=en DIGIKEY_LOCALE_CURRENCY=USD EOF python digikey_mcp_server.py ``` `.mcp.json` for MCP clients: ```json { "mcpServers": { "digikey": { "command": "python", "args": ["digikey_mcp_server.py"], "cwd": "/path/to/digikey-mcp", "env": { "CLIENT_ID": "your_client_id", "CLIENT_SECRET": "your_client_secret", "DIGIKEY_ACCOUNT_ID": "your_customer_number", "USE_SANDBOX": "false", "DIGIKEY_LOCALE_SITE": "US", "DIGIKEY_LOCALE_LANGUAGE": "en", "DIGIKEY_LOCALE_CURRENCY": "USD" } } } } ``` Locale env vars are optional — defaults are `US`/`en`/`USD` (see [Configuration](#configuration)). ## Tools ### Search | Tool | Description | |------|-------------| | `keyword_search` | Search products by keyword with sorting, filtering, manufacturer/category constraints | | `search_manufacturers` | List all manufacturers | | `search_categories` | List all product categories | | `search_product_substitutions` | Find substitute/alternative products | ### Product Details | Tool | Description | |------|-------------| | `product_details` | Full product information for a part number | | `get_category_by_id` | Category details by ID | | `get_product_media` | Images, documents, videos for a product | | `get_product_pricing` | Detailed pricing with quantity breaks | | `get_digi_reel_pricing` | DigiReel-specific pricing | ### Write / Push | Tool | Description | |------|-------------| | `generate_cart_url` | Build a FastAdd URL to populate the DigiKey shopping cart | | `create_mylist_link` | Create a single-use URL to import parts into DigiKey MyLists | > **Locale-aware URLs:** Both tools generate URLs using the domain derived from `DIGIKEY_LOCALE_SITE` (e.g., `AT` → `www.digikey.at`, `DE` → `www.digikey.de`). This ensures links open in the correct regional DigiKey site. Defaults to `www.digikey.com` (US). ### Order Status | Tool | Description | |------|-------------| | `list_orders` | List orders within a date range (last 30 days default) | | `get_order_status` | Get full details of a specific sales order | > **Note:** Order tools require `DIGIKEY_ACCOUNT_ID` (your DigiKey customer number). Without it, these tools return 400 Bad Request. ### Search Options Filters (comma-separated in `search_options`): `LeadFree`, `RoHSCompliant`, `InStock`, `HasDatasheet`, `HasProductPhoto`, `Has3DModel`, `NewProduct` Sort fields: `Packaging`, `ProductStatus`, `DigiKeyProductNumber`, `ManufacturerProductNumber`, `Manufacturer`, `MinimumQuantity`, `QuantityAvailable`, `Price`, `Supplier`, `PriceManufacturerStandardPackage` ## Configuration All settings are controlled via environment variables. In Docker MCP Toolkit mode, these are set in the catalog `env` block or as secrets. In standalone mode, use a `.env` file. | Variable | Default | Description | |----------|---------|-------------| | `CLIENT_ID` | *(required)* | DigiKey API client ID | | `CLIENT_SECRET` | *(required)* | DigiKey API client secret | | `DIGIKEY_ACCOUNT_ID` | *(optional)* | DigiKey customer number. Required for order tools (`list_orders`, `get_order_status`). | | `USE_SANDBOX` | `true` | Use sandbox API (`true`) or production (`false`). The Dockerfile and catalog examples override this to `false`. | | `DIGIKEY_LOCALE_SITE` | `US` | DigiKey site (e.g., `AT`, `DE`, `UK`). Also sets the website domain for cart and MyList URLs (see below). | | `DIGIKEY_LOCALE_LANGUAGE` | `en` | Response language | | `DIGIKEY_LOCALE_CURRENCY` | `USD` | Pricing currency (e.g., `EUR`) | ## Docker MCP Registry This repo is structured for submission to the [docker/mcp-registry](https://github.com/docker/mcp-registry). The [server.yaml](server.yaml) file contains the registry entry reference — this is **not** the same as the local catalog above. When the server is published to the registry, users won't need to create a custom catalog; they'll install it directly via `docker mcp server enable digikey`. ## Troubleshooting **Gateway shows 0 tools:** The server uses lazy OAuth initialization — it won't authenticate until the first tool call. If the gateway still shows no tools, verify the `tools` list in your catalog matches the tool names above. **OAuth errors on first tool call:** Verify your credentials with `docker mcp secret list`. Secret names must be prefixed: `digikey.CLIENT_ID`, not `CLIENT_ID`. **Order tools return 400 Bad Request:** The order endpoints require `DIGIKEY_ACCOUNT_ID`. Set it with `docker mcp secret set digikey.DIGIKEY_ACCOUNT_ID`. The value is your DigiKey customer number, found in your [account settings](https://www.digikey.com/account/myaccount/). **API calls fail with 401 after running for a while:** The server fetches an OAuth token once at startup and does not refresh it. DigiKey tokens expire after ~30 minutes. Restart the MCP client (or container) to obtain a fresh token. **Catalog changes not taking effect:** Re-run `docker mcp catalog import ~/.docker/mcp/catalogs/custom.yaml` after editing the catalog file. Restart your MCP client afterward. ## License MIT License — see [LICENSE](LICENSE).