ETIM MCP服务器
一种生产就绪的模型上下文协议（MCP）服务器，为LLM提供对ETIM Classification API的直接访问。该服务器使Claude等人工智能助手能够从国际ETIM数据库中查询产品分类、技术特征和标准化产品信息。
概述
ETIM技术信息模型 是技术产品分类的国际标准，重点是电气和电子产品。此MCP服务器包装ETIM API v2.0，并通过模型上下文协议将其公开，使任何兼容MCP的AI助手都可以访问标准化的产品数据。
非常适合:
- 🏢 需要标准化产品数据的电子商务平台
- 🔌 电气产品制造商和分销商
- 📊 数据集成和迁移项目
- 🤖 基于人工智能的产品推荐系统
- 🔍 技术产品搜索和比较工具
特性
- 22个MCP工具 全面的ETIM API访问：
- 搜索产品类别、功能、组、功能组、值和单位 - 获取所有ETIM实体的详细信息 - 并排比较多个产品类别 - 跟踪版本之间的分类更改 - 服务器组件的运行状况检查 - 获取支持的语言和ETIM版本
- 2 MCP资源 快速参考：
- 支持的语言列表 - ETIM发布版本
- 3个MCP提示 对于常见工作流：
- 比较两个产品类别 - 查找符合规格的产品 - 详细解释分类
- 智能缓存 使用Redis：
- 搜索结果缓存1小时 - 24小时缓存课程详细信息 - 静态数据（语言、版本）的7天缓存
- 自动OAuth令牌管理:
- 带有5分钟到期缓冲区的令牌缓存 - 401错误自动刷新 - 透明的令牌处理
- 多运输支持:
- stdio -本地Claude桌面/代码集成（默认） - sse -服务器发送远程访问事件（例如Windows→ WSL) - streamable-http -较新的MCP协议变体
- 生产就绪架构:
- Docker编写安装程序并进行健康检查 - 使用Loguru进行结构化日志记录 - 全面的错误处理 - 始终异步/等待性能
先决条件
- 已安装Docker和Docker Compose
- ETIM API凭据（client_id和client_secret）
- 用于ETIM API访问的Internet连接
快速开始
安装
- 克隆仓库:
git clone https://github.com/ziouzitsou/etim-mcp-server.git
cd etim-mcp-server- 创建
.env文件 从示例模板中：
cp .env.example .env- 编辑
.env并添加您的ETIM API凭据：
ETIM_CLIENT_ID=your_client_id_here
ETIM_CLIENT_SECRET=your_client_secret_here- 构建并启动服务:
docker-compose up --build服务器将：
- 在端口6379上启动Redis
- 启动MCP服务器（可通过stdio访问）
- 启动Redis Commanderhttp://localhost:8081（用于缓存监控）
配置
所有配置均通过环境变量进行管理 .env 文件：
必需设置
| 变量 | 描述 | 默认值 |
|---|---|---|
ETIM_CLIENT_ID | 您的ETIM API客户端ID | （必需） |
ETIM_CLIENT_SECRET | 您的ETIM API客户端机密 | （必需） |
可选设置
| 变量 | 描述 | 默认值 |
|---|---|---|
ETIM_AUTH_URL | ETIM OAuth身份验证URL | https://etimauth.etim-international.com |
ETIM_API_URL | ETIM API基础URL | https://etimapi.etim-international.com |
ETIM_DEFAULT_LANGUAGE | 查询的默认语言 | EN |
REDIS_HOST | Redis服务器主机名 | redis |
REDIS_PORT | Redis服务器端口 | 6379 |
REDIS_PASSWORD | Redis密码（如果需要） | （空） |
CACHE_TTL | 默认缓存TTL（秒） | 3600 （1小时） |
CACHE_CLASS_TTL | 类详细信息缓存TTL | 86400 （24小时） |
CACHE_LANGUAGES_TTL | 语言/释放缓存TTL | 604800 （7天） |
LOG_LEVEL | 日志记录级别 | INFO |
MCP_TRANSPORT | 运输方式： stdio, sse，或 streamable-http | stdio |
MCP_HOST | 要绑定HTTP传输的主机 | 0.0.0.0 |
MCP_PORT | HTTP传输端口 | 8000 |
支持的语言
支持以下语言代码（取决于您的ETIM帐户）：
EN-英语de-DE-德语nl-BE-荷兰语（比利时）fr-BE-法语（比利时）fi-FI-芬兰语it-IT-意大利语nb-NO-挪威语
用法
运行服务器
使用Docker Compose启动服务器：
docker-compose up对于分离模式（在后台运行）：
docker-compose up -d查看日志：
docker-compose logs -f mcp-server停止服务器：
docker-compose down使用Claude代码进行测试
对于在同一目录中使用Claude Code进行测试 mcp.json 文件包括：
# Open a new Claude Code terminal in this directory
cd "/home/sysadmin/Foss Google Drive/ETIM/ETIM_API/etim-mcp-server"
# Claude Code will automatically detect and use the mcp.json configuration
# Try commands like: "Search ETIM for cable products"这 mcp.json 该文件包含MCP服务器配置，并允许Claude Code连接到ETIM服务器进行测试。
Claude桌面集成
要将此MCP服务器与Claude Desktop一起使用，请将以下内容添加到您的Claude配置中：
在macOS上: ~/Library/Application Support/Claude/claude_desktop_config.json
在Windows上: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"etim": {
"command": "docker",
"args": [
"compose",
"-f",
"/absolute/path/to/etim-mcp-server/docker-compose.yml",
"run",
"--rm",
"mcp-server"
]
}
}
}替换 /absolute/path/to/etim-mcp-server 安装的实际路径。
添加此配置后：
- 重新启动克劳德桌面
- ETIM工具应出现在Claude的可用工具中
- 试着问：“在ETIM中搜索有线电视产品”
通过SSE（例如Windows）进行远程访问→ WSL)
要远程访问MCP服务器（例如，从Windows Claude Desktop到WSL中运行的服务器）：
- 将服务器配置为SSE模式 在你的
.env:
MCP_TRANSPORT=sse
MCP_HOST=0.0.0.0
MCP_PORT=8000- 启动服务器 （它将在端口8000上监听）：
docker-compose up -d- 在Windows上配置Claude桌面 通过SSE连接：
{
"mcpServers": {
"etim": {
"url": "http://:8000/sse"
}
}
}替换 ` 使用您的WSL IP地址（使用查找 hostname -I` WSL）。
可用工具
搜索类
按关键字搜索ETIM产品类别。
参数:
search_text（必填）：搜索查询（例如“电缆”、“筒灯”）language（可选）：语言代码（默认：EN）max_results（可选）：返回的最大结果（1-100，默认值：10）
示例：“搜索LED筒灯产品”
get_class_details
获取特定ETIM产品类别的详细信息。
参数:
class_code（必填）：ETIM类代码（例如“EC001744”）version（可选）：特定版本号（如果没有提供，则为最新版本）language（可选）：语言代码（默认：EN）include_features（可选）：包括完整功能列表（默认值：true）
示例：“获取ETIM类EC001744的详细信息”
搜索功能
搜索ETIM特征/特性。
参数:
search_text（必填）：搜索查询language（可选）：语言代码（默认：EN）max_results（可选）：最大结果（1-100，默认值：10）
示例：“搜索IP评级功能”
get_feature_details
获取特定ETIM功能的详细信息。
参数:
feature_code（必填）：ETIM功能代码（例如“EF007793”）language（可选）：语言代码（默认：EN）
示例：“获取功能EF007793的详细信息”
搜索组
搜索ETIM产品组。
参数:
search_text（必填）：搜索查询language（可选）：语言代码（默认：EN）max_results（可选）：最大结果（1-100，默认值：10）
示例：“搜索照明产品组”
get_supported_语言
获取您的ETIM帐户支持的语言列表。
参数：无
示例
get_etim_releases
获取ETIM发布版本列表。
参数：无
示例：“显示ETIM发布版本”
get_all_语言
获取全球所有ETIM语言的列表（不仅仅是特定于帐户的语言）。
参数：无
示例：“显示全球可用的所有ETIM语言”
备注：这与 get_supported_languages 它只返回您的帐户可以访问的语言。
get_class_details_many
在单个请求中获取多个类的详细信息（批处理操作）。
参数:
classes（必填）：带有“code”和可选“version”的类词典列表
- 例子： [{"code": "EC003025", "version": 1}, {"code": "EC003025", "version": 2}]
language（可选）：语言代码（默认：EN）include_features（可选）：包括完整功能列表（默认值：true）
示例：“获取EC001744类版本1和版本2的详细信息”
用例：批量目录更新、版本比较、数据迁移
get_all_class_versions
获取特定类的所有版本（完整的版本历史记录）。
参数:
class_code（必填）：ETIM类代码（例如“EC002883”）language（可选）：语言代码（默认：EN）include_features（可选）：包括完整功能列表（默认值：性能为false）
示例：“显示类EC002883的所有版本”
用例：分类演变跟踪、迁移规划、变更历史
get_class_for_release
获取特定ETIM发布版本的类详细信息。
参数:
class_code（必填）：ETIM类代码（例如“EC000034”）release（必填）：ETIM发布名称（例如，“ETIM-9.0”、“ETIM-10.0”）language（可选）：语言代码（默认：EN）include_features（可选）：包括完整功能列表（默认值：true）
示例：“获取ETIM-9.0中的EC000034类”
用例：针对特定版本、遗留系统兼容性、版本比较进行测试
比较类
并排比较多个ETIM产品类别。
参数:
class_codes（必填）：要比较的类代码列表（最多5个）language（可选）：语言代码（默认：EN）
示例：“比较类EC001744和EC001679”
搜索值
搜索ETIM特征值（颜色、材质、连接器类型等）。
参数:
search_text（必填）：搜索查询language（可选）：语言代码（默认：EN）deprecated（可选）：包含已弃用的值（默认值：false）max_results（可选）：最大结果（1-100，默认值：10）
示例：“搜索红色值”
get_value_details
获取特定ETIM值的详细信息。
参数:
value_code（必填）：ETIM值代码（例如“EV000397”）language（可选）：语言代码（默认：EN）
示例：“获取价值EV000397的详细信息”
搜索单位
搜索测量单位（毫米、瓦、伏等）。
参数:
search_text（必填）：搜索查询language（可选）：语言代码（默认：EN）deprecated（可选）：包含已弃用的单位（默认值：false）max_results（可选）：最大结果（1-100，默认值：10）
示例：“搜索毫米单位”
获取详细信息
获取特定测量单位的详细信息。
参数:
unit_code（必填）：ETIM单位代码（例如“EU571097”）language（可选）：语言代码（默认：EN）
示例：“获取EU571097单元的详细信息”
搜索_特征_组
搜索ETIM要素组（要素的组织类别）。
参数:
search_text（必填）：搜索查询language（可选）：语言代码（默认：EN）max_results（可选）：最大结果（1-100，默认值：10）
示例：“搜索电气功能组”
get_feature_group_details
获取特定功能组的详细信息。
参数:
feature_group_code（必填）：ETIM功能组代码（例如“EFG00004”）language（可选）：语言代码（默认：EN）
示例：“获取功能组EFG00004的详细信息”
get_group_details
获取特定产品组的详细信息。
参数:
group_code（必填）：ETIM组码（例如“EG020005”）language（可选）：语言代码（默认：EN）include_releases（可选）：包括发布信息（默认值：true）
示例：“获取组EG020005的详细信息”
get_class_diff
获取与前一版本相比的类详细信息。非常适合跟踪分类演变和了解版本之间的变化。
参数:
class_code（必填）：ETIM类代码（例如“EC000034”）version（必填）：要比较的类版本（必须是版本2或更高版本）language（可选）：语言代码（默认：EN）
示例：“显示EC000034版本7中的更改内容”
健康检查
检查服务器运行状况和连接状态。
参数：无
示例：“检查ETIM服务器运行状况”
建筑
┌─────────────────────┐ ┌─────────────────────┐
│ Claude Desktop │ │ Claude Desktop │
│ (Local - stdio) │ │ (Remote - SSE) │
└──────────┬──────────┘ └──────────┬──────────┘
│ stdio │ HTTP :8000
│ │
┌──────────▼───────────────────────────▼──────────┐
│ FastMCP Server │
│ (Python/AsyncIO) │
├─────────────────────────────────────────────────┤
│ • Multi-Transport (stdio/sse/streamable-http) │
│ • Auth Manager │
│ • API Client │
│ • Cache Layer │
└─────┬───────────────────────────────────────────┘
│
│ TCP
┌─────▼──────┐
│ Redis │
│ (Cache) │
└─────┬──────┘
│
┌─────▼──────────────┐
│ ETIM API v2.0 │
│ (OAuth2 + REST) │
└────────────────────┘组件
- FastMCP服务器 (
server.py)：带工具、资源和提示的主MCP服务器 - ETIM API客户端 (
client.py)：ETIM API的异步HTTP客户端，带缓存 - 令牌管理器 (
auth.py)：具有自动刷新功能的OAuth2令牌管理 - Redis 缓存 (
cache.py)：用于响应缓存的异步Redis包装器 - 配置 (
config.py)：环境变量中的Pydantic设置
发展
地方发展设置
- 安装Python 3.11+：
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt- 在本地运行Redis：
docker run -d -p 6379:6379 redis:7-alpine- 创建
.env将您的凭据归档
- 运行服务器：
python -m mcp run src.etim_mcp.server:mcp项目结构
etim-mcp-server/
├── docker-compose.yml # Docker orchestration
├── Dockerfile # Container image definition
├── requirements.txt # Python dependencies
├── .env # Configuration (not in git)
├── .env.example # Configuration template
├── .gitignore # Git ignore rules
├── README.md # This file
└── src/
└── etim_mcp/
├── __init__.py # Package initialization
├── server.py # FastMCP server with tools
├── client.py # ETIM API client
├── auth.py # OAuth token manager
├── cache.py # Redis cache wrapper
└── config.py # Settings management测试
使用MCP检查员测试单个工具：
npx @modelcontextprotocol/inspector docker compose run --rm mcp-server或者直接测试API连接：
# Enter the container
docker-compose run --rm mcp-server bash
# Run Python interactively
python
>>> from etim_mcp.config import settings
>>> from etim_mcp.cache import RedisCache
>>> from etim_mcp.auth import EtimTokenManager
>>> from etim_mcp.client import EtimAPIClient
>>> import asyncio
>>>
>>> async def test():
... cache = RedisCache(settings.redis_host, settings.redis_port, settings.redis_password)
... await cache.connect()
... token_mgr = EtimTokenManager(cache)
... client = EtimAPIClient(token_mgr, cache)
... result = await client.get_allowed_languages()
... print(result)
... await client.close()
... await token_mgr.close()
... await cache.close()
>>>
>>> asyncio.run(test())监控
Redis指挥官
访问Redis Commander web UIhttp://localhost:8081致：
- 查看缓存的键及其值
- 监控缓存命中率/未命中率
- 检查令牌存储
- 如果需要，手动清除缓存
日志
查看带有时间戳的结构化日志：
docker-compose logs -f mcp-server日志级别可以在中调整 .env:
DEBUG：详细日志记录，包括缓存操作INFO：正常操作日志（默认）WARNING：仅警告和错误ERROR：只有错误
故障排除
服务器无法启动
问题: Failed to connect to Redis
解决方案：确保Redis运行正常：
docker-compose ps
docker-compose logs redis身份验证错误
问题: Failed to obtain access token: 401
解决方案：在中验证您的凭据 .env:
- 检查
ETIM_CLIENT_ID是正确的 - 检查
ETIM_CLIENT_SECRET是正确的 - 确保没有多余的空格或引号
API请求失败
问题: HTTP error: 401 在API调用期间
解决方案：服务器会自动刷新令牌，但如果问题仍然存在：
- 检查ETIM API状态
- 验证您的帐户是否可以访问请求的资源
- 清除Redis缓存：
docker-compose down -v && docker-compose up
Claude Desktop找不到服务器
问题：工具未出现在Claude Desktop中
解决方案:
- 验证中的绝对路径
claude_desktop_config.json - 确保
.env文件存在有效凭据 - 手动测试服务器：
docker-compose run --rm mcp-server - 完全重新启动克劳德桌面
- 检查Claude Desktop日志中的MCP错误
反应缓慢
问题：查询时间过长
解决方案:
- 检查Redis是否正常工作：
docker-compose logs redis - 第一次查询速度较慢（缓存未命中）-后续查询应该很快
- 在Redis Commander中监控缓存命中率
- 在中调整缓存TTL
.env如有需要
清除所有缓存数据
docker-compose down -v
docker-compose up -d这 -v 标志删除卷，包括Redis数据。
演出
- 首次请求延迟：500-1000ms（OAuth+neneneba API调用）
- 缓存请求延迟：10-50ms（Redis查找）
- 令牌刷新：自动，对用户透明
- 缓存命中率：对于重复查询，通常为70-90%
安全
- OAuth令牌与适当的TTL一起存储在Redis中
- 凭据仅从环境变量加载
- 响应中没有记录或公开凭据
- Redis只能在Docker网络内访问（不对外公开）
贡献
欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。
看 贡献.md 详细指南。
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
致谢
支持
对于ETIM API问题或问题：
- ETIM国际网站：https://www.etim-international.com/
- ETIM API文档：https://etimapi.etim-international.com/swagger/index.html
对于MCP协议问题：
- 模型上下文协议：https://github.com/modelcontextprotocol
- FastMCP文档：https://github.com/modelcontextprotocol/python-sdk
版本历史
- 1.4.0 （当前）：多种运输支持
- 为远程访问添加了SSE和Streamable HTTP传输模式 - 新环境变量： MCP_TRANSPORT, MCP_HOST, MCP_PORT - 非常适合Windows Claude桌面→ WSL服务器场景 - 添加uvicorn作为HTTP传输的ASGI服务器
- 1.3.0：增强的功能控制和分页
- 新 features 参数有4种模式（无/计数/摘要/完整） - 新 get_class_features 分页功能访问工具 - 突发: include_features 现在默认为 False - 现在涵盖22个MCP工具
- 1.2.0：第2阶段扩展-批量操作和完成API覆盖范围
- 添加了4个新工具：所有语言、批处理类详细信息、所有类版本、发布类 - 现在涵盖21个MCP工具（从17个增加到21个） - 将API覆盖率从可用端点的60%提高到76%
- 1.1.0：第一阶段扩建
- 添加了8个新工具：值、单位、要素组、组详细信息、类差异 - 现在涵盖17个MCP工具（从9个增加到17个）
- 1.0.0：初始版本包含9个工具、Redis缓存和Docker Compose设置