内容
# DigiKey MCP 服务器
一个适用于 DigiKey 产品搜索 API v4 的 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，使用 [FastMCP](https://github.com/jlowin/fastmcp) 构建。优先采用 Docker，专为 [Docker MCP 工具包](https://docs.docker.com/ai/mcp-catalog-and-toolkit/) 设计。
最初灵感来自 [bengineer19/digikey_mcp](https://github.com/bengineer19/digikey_mcp)。
## 先决条件
- **DigiKey API 凭证** — 在 [developer.digikey.com](https://developer.digikey.com/) 注册，创建一个具有 `client_credentials` 授权类型的应用程序
- **DigiKey 客户编号** — 订购工具所需。在 [DigiKey 账户设置](https://www.digikey.com/account/myaccount/) 中查找
- **Docker** （推荐）或 Python 3.10+
- **Docker MCP 工具包** — 包含在 [Docker Desktop](https://www.docker.com/products/docker-desktop/) 中（需要 MCP 工具包支持）
## 项目结构
```
digikey-mcp/
├── mcp_app.py # 共享 FastMCP 实例
├── digikey_mcp_server.py # 主服务器 — 认证工具（OAuth2）
├── digikey_noauth_tools.py # 无认证工具（购物车网址、MyList 链接）
├── Dockerfile # 带有嵌入元数据的 Docker 镜像
├── server.yaml # docker/mcp-registry 的注册表条目
└── tests/ # 单元测试
```
## 快速入门 — Docker MCP 工具包
运行此服务器的推荐方式。Docker MCP 网关管理容器生命周期，注入机密，并向 MCP 客户端（如 Claude Code 或 Claude Desktop）公开工具。
### 1. 构建 Docker 镜像
```bash
git clone https://github.com/simon-77/digikey-mcp.git
cd digikey-mcp
docker build -t digikey-mcp:latest .
```
### 2. 创建自定义目录
网关通过目录文件发现服务器。在 `~/.docker/mcp/catalogs/custom.yaml` 处创建一个：
```yaml
version: 3
name: custom
displayName: 自定义 MCP 服务器
registry:
digikey:
description: DigiKey 元件搜索、定价、订购和订单状态
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: "zh"
- name: DIGIKEY_LOCALE_CURRENCY
value: "USD"
tools:
- name: 关键词搜索
- name: 产品详情
- name: 搜索制造商
- name: 搜索类别
- name: 按 ID 获取类别
- name: 搜索产品替代品
- name: 获取产品媒体
- name: 获取产品定价
- name: 获取 DigiReel 定价
- name: 生成购物车网址
- name: 创建 MyList 链接
- name: 列出订单
- name: 获取订单状态
prompts: 0
resources: {}
```
将 `env` 值更改为匹配您的地区（例如 `CN`/`zh`/`CNY` 表示中国）。
> **注意：** `tools` 列表必须与服务器中定义的工具匹配。网关使用此列表向 MCP 客户端注册工具。`prompts: 0` 和 `resources: {}` 表示服务器不公开任何 MCP 提示或资源。
### 3. 注册目录并启用服务器
```bash
docker mcp catalog import ~/.docker/mcp/catalogs/custom.yaml
docker mcp server enable digikey
```
重新运行 `catalog import` 每当您修改 `custom.yaml` 时。
### 4. 设置机密
```bash
docker mcp secret set digikey.CLIENT_ID
docker mcp secret set digikey.CLIENT_SECRET
docker mcp secret set digikey.DIGIKEY_ACCOUNT_ID
```
您将被提示输入每个值。机密名称 **必须** 以服务器名称 (`digikey.`) 为前缀。
账户 ID 是您的 DigiKey 客户编号 — 订购工具所需。
### 5. 连接 MCP 客户端
```bash
docker mcp client connect claude-code
```
这将网关添加到您的项目的 `.mcp.json` 中：
```json
{
"mcpServers": {
"MCP_DOCKER": {
"command": "docker",
"args": ["mcp", "gateway", "run"],
"type": "stdio"
}
}
}
```
当 MCP 客户端启动时，网关启动 `digikey-mcp:latest` 容器，将机密作为环境变量注入，并代理工具调用。
### 重新构建更改后
```bash
docker build -t digikey-mcp:latest .
# 重启 MCP 客户端以获取新镜像
```
无需重新导入目录或重新设置机密 — 只需重新构建和重启。
## 替代：独立 Docker
直接运行容器，无需 MCP 工具包。您自己管理机密和生命周期。
```bash
docker build -t digikey-mcp .
docker run --rm -i \
-e CLIENT_ID=您的客户端 ID \
-e CLIENT_SECRET=您的客户端密钥 \
-e DIGIKEY_ACCOUNT_ID=您的客户编号 \
-e USE_SANDBOX=false \
-e DIGIKEY_LOCALE_SITE=US \
-e DIGIKEY_LOCALE_LANGUAGE=zh \
-e DIGIKEY_LOCALE_CURRENCY=USD \
digikey-mcp
```
MCP 客户端的 `.mcp.json`：
```json
{
"mcpServers": {
"digikey": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CLIENT_ID=您的客户端 ID",
"-e", "CLIENT_SECRET=您的客户端密钥",
"-e", "DIGIKEY_ACCOUNT_ID=您的客户编号",
"-e", "USE_SANDBOX=false",
"-e", "DIGIKEY_LOCALE_SITE=US",
"-e", "DIGIKEY_LOCALE_LANGUAGE=zh",
"-e", "DIGIKEY_LOCALE_CURRENCY=USD",
"digikey-mcp"
]
}
}
}
```
区域环境变量是可选的 — 默认值为 `US`/`zh`/`USD` （参见 [配置](#配置)）。
## 替代：独立（pip）
无需 Docker 运行。需要 Python 3.10+。
```bash
git clone https://github.com/simon-77/digikey-mcp.git
cd digikey-mcp
pip install .
cat > .env <<EOF
CLIENT_ID=您的客户端 ID
CLIENT_SECRET=您的客户端密钥
DIGIKEY_ACCOUNT_ID=您的客户编号
USE_SANDBOX=false
DIGIKEY_LOCALE_SITE=US
DIGIKEY_LOCALE_LANGUAGE=zh
DIGIKEY_LOCALE_CURRENCY=USD
EOF
python digikey_mcp_server.py
```
MCP 客户端的 `.mcp.json`：
```json
{
"mcpServers": {
"digikey": {
"command": "python",
"args": ["digikey_mcp_server.py"],
"cwd": "/path/to/digikey-mcp",
"env": {
"CLIENT_ID": "您的客户端 ID",
"CLIENT_SECRET": "您的客户端密钥",
"DIGIKEY_ACCOUNT_ID": "您的客户编号",
"USE_SANDBOX": "false",
"DIGIKEY_LOCALE_SITE": "US",
"DIGIKEY_LOCALE_LANGUAGE": "zh",
"DIGIKEY_LOCALE_CURRENCY": "USD"
}
}
}
}
```
区域环境变量是可选的 — 默认值为 `US`/`zh`/`USD` （参见 [配置](#配置)）。
## 工具
### 搜索
| 工具 | 描述 |
|------|-------------|
| `关键词搜索` | 按关键词搜索产品，支持排序、筛选、制造商/类别约束 |
| `搜索制造商` | 列出所有制造商 |
| `搜索类别` | 列出所有产品类别 |
| `搜索产品替代品` | 查找替代/类似产品 |
### 产品详情
| 工具 | 描述 |
|------|-------------|
| `产品详情` | 零件号的完整产品信息 |
| `按 ID 获取类别` | 按 ID 获取类别详情 |
| `获取产品媒体` | 产品图片、文档、视频 |
| `获取产品定价` | 详细的定价信息，含数量折扣 |
| `获取 DigiReel 定价` | DigiReel 特定定价 |
### 编写/推送
| 工具 | 描述 |
|------|-------------|
| `生成购物车网址` | 构建 FastAdd 网址以填充 DigiKey 购物车 |
| `创建 MyList 链接` | 创建一次性网址以将零件导入 DigiKey MyLists |
> **区域感知网址：** 两个工具都使用 `DIGIKEY_LOCALE_SITE` 得出的域名生成网址（例如 `CN` → `www.digikey.cn`）。确保链接在正确的区域 DigiKey 网站中打开。默认值为 `www.digikey.com` （美国）。
### 订单状态
| 工具 | 描述 |
|------|-------------|
| `列出订单` | 在日期范围内列出订单（默认为最近 30 天） |
| `获取订单状态` | 获取特定销售订单的完整详情 |
> **注意：** 订单工具需要 `DIGIKEY_ACCOUNT_ID` （您的 DigiKey 客户编号）。如果没有它，这些工具将返回 400 错误请求。
### 搜索选项
筛选器（`search_options` 中以逗号分隔）：`LeadFree`、`RoHSCompliant`、`InStock`、`HasDatasheet`、`HasProductPhoto`、`Has3DModel`、`NewProduct`
排序字段：`Packaging`、`ProductStatus`、`DigiKeyProductNumber`、`ManufacturerProductNumber`、`Manufacturer`、`MinimumQuantity`、`QuantityAvailable`、`Price`、`Supplier`、`PriceManufacturerStandardPackage`
## 配置
所有设置均通过环境变量控制。在 Docker MCP 工具包模式下，这些变量在目录的 `env` 块或作为机密中设置。在独立模式下，使用 `.env` 文件。
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CLIENT_ID` | *必填* | DigiKey API 客户端 ID |
| `CLIENT_SECRET` | *必填* | DigiKey API 客户端密钥 |
| `DIGIKEY_ACCOUNT_ID` | *可选* | DigiKey 客户编号。订单工具 (`list_orders`, `get_order_status`) 必需。 |
| `USE_SANDBOX` | `true` | 使用沙箱 API (`true`) 或生产环境 (`false`)。Dockerfile 和目录示例覆盖此值为 `false`。 |
| `DIGIKEY_LOCALE_SITE` | `US` | DigiKey 网站（例如 `CN`、`DE`、`UK`）。还设置购物车和 MyList 网址的网站域名（参见下文）。 |
| `DIGIKEY_LOCALE_LANGUAGE` | `zh` | 响应语言 |
| `DIGIKEY_LOCALE_CURRENCY` | `USD` | 定价货币（例如 `CNY`） |
## Docker MCP 注册表
此存储库的结构适用于提交到 [docker/mcp-registry](https://github.com/docker/mcp-registry)。`server.yaml` 文件包含注册表条目参考 — 这与上述本地目录 **不同**。当服务器发布到注册表时，用户无需创建自定义目录；他们可以直接通过 `docker mcp server enable digikey` 安装。
## 故障排除
**网关显示 0 个工具：** 服务器使用延迟 OAuth 初始化 — 它在第一次工具调用之前不会认证。如果网关仍然显示没有工具，请验证目录中的 `tools` 列表是否与上述工具名称匹配。
**第一次工具调用时出现 OAuth 错误：** 使用 `docker mcp secret list` 验证您的凭证。机密名称必须带有前缀：`digikey.CLIENT_ID`，而不是 `CLIENT_ID`。
**订单工具返回 400 错误请求：** 订单端点需要 `DIGIKEY_ACCOUNT_ID`。使用 `docker mcp secret set digikey.DIGIKEY_ACCOUNT_ID` 设置它。该值是您的 DigiKey 客户编号，在您的 [账户设置](https://www.digikey.com/account/myaccount/) 中找到。
**API 调用在运行一段时间后出现 401 错误：** 服务器在启动时获取 OAuth 令牌，并且不会刷新它。DigiKey 令牌在约 30 分钟后过期。重启 MCP 客户端（或容器）以获取新的令牌。
**目录更改未生效：** 编辑目录文件后，重新运行 `docker mcp catalog import ~/.docker/mcp/catalogs/custom.yaml`。之后重启您的 MCP 客户端。
## 许可证
MIT 许可证 — 请参阅 [LICENSE](LICENSE)。
