使用说明

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://<WSL-IP>:8000/sse"
    }
  }
}
```
替换 <WSL-IP> 使用您的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许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

建于快速MCP
由...驱动 ETIM国际
使用Redis进行缓存，httpx用于异步HTTP，Pydantic用于配置
在以下人员的协助下开发和测试人类克劳德密码，基于原始代码库和项目维护人员的指导

支持

对于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设置

使用说明

ETIM MCP服务器

概述

特性

先决条件

快速开始

安装

配置

必需设置

可选设置

支持的语言

用法

运行服务器

使用Claude代码进行测试

Claude桌面集成

通过SSE（例如Windows）进行远程访问→ WSL)

可用工具

搜索类

get_class_details

搜索功能

get_feature_details

搜索组

get_supported_语言

get_etim_releases

get_all_语言

get_class_details_many

get_all_class_versions

get_class_for_release

比较类

搜索值

get_value_details

搜索单位

获取详细信息

搜索_特征_组

get_feature_group_details

get_group_details

get_class_diff

健康检查

建筑

组件

发展

地方发展设置

项目结构

测试

监控

Redis指挥官

日志

故障排除

服务器无法启动

身份验证错误

API请求失败

Claude Desktop找不到服务器

反应缓慢

清除所有缓存数据

演出

安全

贡献

许可证

致谢

支持

版本历史

相关 MCP

关税查询工具

产品智能分类系统

网页内容抓取服务器

知识图谱记忆服务器

顺序思维服务器

Figma MCP服务器