智谱AI MCP 服务器

基于智谱AI Web Search API 实现的 MCP (Model Context Protocol) 服务器，为大模型提供网络搜索能力。

使用 Streamable HTTP 协议传输

功能特性

🔍 多搜索引擎支持：智谱基础版、高阶版、搜狗、夸克
🎯 意图识别：可选的搜索意图识别，优化搜索结果
⏰ 时间过滤：支持一天/一周/一个月/一年内的时间范围过滤
🌐 域名过滤：支持白名单域名限制
📊 结构化输出：返回标题、URL、摘要、来源等信息
🚀 Streamable HTTP：使用高效的 HTTP 流式传输协议

安装

使用 uv（推荐）

cd zhipu_mcp
uv sync

使用 pip

cd zhipu_mcp
pip install -e .

配置

1. 获取 API Key

前往智谱AI开放平台获取 API Key。

2. 设置环境变量

export ZHIPU_API_KEY="your-api-key-here"

启动服务器

# 使用默认配置启动 (127.0.0.1:8000/mcp)
uv run zhipu-websearch-mcp

# 或指定参数
uv run zhipu-websearch-mcp --host 0.0.0.0 --port 9000 --path /api/mcp

命令行参数

| 参数 | 默认值 | 说明 | |------|--------|------| | --host | 127.0.0.1 | 监听地址 | | --port | 8000 | 监听端口 | | --path | /mcp | MCP端点路径 |

配置 MCP 客户端

Claude Desktop 配置

编辑 Claude Desktop 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置（使用 Streamable HTTP URL）：

{
  "mcpServers": {
    "zhipu": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

注意：需要先启动 MCP 服务器，再启动 Claude Desktop。

Cursor 配置

在 Cursor 的 MCP 设置中添加：

{
  "zhipu": {
    "url": "http://127.0.0.1:8000/mcp"
  }
}

工具说明

web_search - 网络搜索

使用智谱AI网络搜索引擎搜索互联网内容。

参数

| 参数 | 类型 | 必需 | 默认值 | 说明 | |------|------|------|--------|------| | query | string | ✅ | - | 搜索查询内容，建议不超过70个字符 | | search_engine | string | ❌ | search_std | 搜索引擎类型 | | search_intent | boolean | ❌ | false | 是否进行搜索意图识别 | | count | integer | ❌ | 10 | 返回结果条数，范围1-50 | | search_domain_filter | string | ❌ | - | 白名单域名过滤 | | search_recency_filter | string | ❌ | noLimit | 时间范围过滤 | | content_size | string | ❌ | medium | 内容详细程度 |

搜索引擎类型

| 值 | 说明 | |----|------| | search_std | 智谱基础版搜索引擎 | | search_pro | 智谱高阶版搜索引擎 | | search_pro_sogou | 搜狗搜索 | | search_pro_quark | 夸克搜索 |

时间范围过滤

| 值 | 说明 | |----|------| | oneDay | 一天内 | | oneWeek | 一周内 | | oneMonth | 一个月内 | | oneYear | 一年内 | | noLimit | 不限（默认） |

内容详细程度

| 值 | 说明 | |----|------| | medium | 返回摘要信息，满足常规问答需求 | | high | 最大化上下文，信息量大，适合需要细节的场景 |

使用示例

在 Claude 或 Cursor 中，你可以这样使用：

请搜索最近一周关于"人工智能"的新闻

MCP 将自动调用 web_search 工具，返回结构化的搜索结果。

Docker 部署

使用 Docker Compose（本地测试）

# 设置环境变量
export ZHIPU_API_KEY="your-api-key-here"

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

使用 Dokploy 部署

在 Dokploy 中创建新项目
选择 Git Repository 或 Docker 部署方式
配置构建设置：

如果使用 Git Repository，Dokploy 会自动检测 Dockerfile
端口设置为 8000

在 Environment Variables 中添加：

ZHIPU_API_KEY: 你的智谱 AI API 密钥

部署后，MCP 端点地址为：http://your-domain:8000/mcp

Dokploy 环境变量配置

| 变量名 | 必需 | 说明 | |--------|------|------| | ZHIPU_API_KEY | ✅ | 智谱AI API密钥 |

手动 Docker 部署

# 构建镜像
docker build -t zhipu-mcp .

# 运行容器
docker run -d \
  --name zhipu-mcp \
  -p 8000:8000 \
  -e ZHIPU_API_KEY="your-api-key-here" \
  zhipu-mcp

开发

运行测试

uv run python -c "from zhipu_mcp.server import mcp; print('Import successful')"

调试模式

可以使用 MCP Inspector 进行调试：

npx @anthropic-ai/mcp-inspector

然后在 Inspector 中连接到 http://127.0.0.1:8000/mcp。

许可证

MIT License

zhipu-mcp