icon_mcp

基于 MCP (Model Context Protocol) 的图标服务器，用于从 iconfont.cn 搜索和获取图标。

功能特性

• 🔍 图标搜索: 从 iconfont.cn 搜索图标
• 🎨 SVG 获取: 获取图标的 SVG 格式内容
• ⚡ 缓存机制: 内置内存缓存，30分钟过期
• 🖥️ Web 界面: 提供可视化图标选择和保存功能（HTTP + WebSocket）
• 🌐 多语言: 支持中文 (zh-CN) 和英文 (en)
• 📦 类型安全: 使用 Pydantic 数据模型
• 🔄 全异步: 基于 asyncio / aiohttp / httpx

技术栈

组件	技术
MCP 协议	mcp Python SDK (stdio transport)
HTTP 服务	aiohttp (HTTP + WebSocket)
HTTP 客户端	httpx (异步请求 iconfont.cn API)
数据模型	pydantic
包管理	uv
Python 版本	>= 3.10

安装

# 使用 uv 初始化虚拟环境并安装依赖
uv sync

# 或者直接安装
uv pip install -e .

使用方法

1. 直接运行（推荐）

uv run python run.py
uv run python run.py --port 8080 --language zh-CN

2. 使用命令行入口

uv run icon-mcp

3. 使用模块方式运行

uv run python -m icon_mcp

4. 自定义端口运行

uv run python run.py --port 8080
uv run python run.py --port 8080 --language zh-CN --auto-start-web --auto-open

4. 环境变量配置

export LANGUAGE=zh-CN
export WEB_SERVER_PORT=8080
export WEB_SERVER_AUTO_OPEN=true
export AUTO_START_WEB_SERVER=true

5. 命令行参数说明

参数	说明	默认值
--port	Web 服务器端口	3000
--language	界面语言 (en / zh-CN)	en
--auto-start-web	启动时自动开启 Web 服务器	false
--auto-open	自动打开浏览器	false

编辑器集成

Claude Code（命令行）

通过 claude mcp add 命令一键添加：

# 基本用法
claude mcp add icon-mcp -- uv --directory /path/to/icon_mcp run python run.py

# 指定自定义端口
claude mcp add icon-mcp -- uv --directory /path/to/icon_mcp run python run.py --port 8080

# 中文 + 自定义端口 + 自动启动 Web
claude mcp add icon-mcp -- uv --directory /path/to/icon_mcp run python run.py --port 8080 --language zh-CN --auto-start-web

# 添加后查看已注册的 MCP
claude mcp list

注意: 将 /path/to/icon_mcp 替换为项目实际路径。

Cursor / Claude Desktop 配置（JSON）

在 .cursor/mcp.json 或 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "icon": {
      "command": "uv",
      "args": ["--directory", "/path/to/icon_mcp", "run", "python", "run.py", "--port", "8080"],
      "env": {
        "LANGUAGE": "zh-CN"
      }
    }
  }
}

MCP 工具列表

工具名称	描述
search_icons	从 iconfont.cn 搜索图标
start_web_server	启动 Web 图标选择界面
stop_web_server	停止 Web 服务器
check_selection_status	轮询检查用户图标选择状态
get_cache_stats	获取缓存统计信息
clear_cache	清除缓存
save_icons	保存图标 SVG 到本地文件

项目结构

icon_mcp/
├── pyproject.toml           # 项目配置 (uv/hatch)
├── README.md
└── src/
    └── icon_mcp/
        ├── __init__.py      # 包信息
        ├── __main__.py      # 入口点 (python -m icon_mcp)
        ├── server.py        # MCP Server 核心 (工具注册 & 调度)
        ├── config.py        # 配置管理
        ├── models.py        # Pydantic 数据模型
        ├── utils/
        │   ├── cache.py     # 缓存管理器
        │   ├── search.py    # 图标搜索逻辑
        │   ├── saver.py     # 图标保存
        │   └── web_server.py # HTTP + WebSocket 服务器
        ├── web/
        │   └── interface.py # Web UI HTML/JS 生成
        └── lang/
            ├── __init__.py  # i18n 核心 (t() 翻译函数)
            ├── en.py        # 英文翻译
            └── zh_cn.py     # 中文翻译

贡献

欢迎提交 Pull Request 来改进这个项目！如果你觉得这个项目有帮助，请给一个 ⭐ Star 支持一下。