Python五步搭建MCP服务器！4SAPI接入Claude

MCP Server（Model Context Protocol服务器）作为连接AI模型与外部工具的标准化接口，自Anthropic于2024年底开源以来，已迅速确立其行业地位。截至2026年4月，Python SDK在PyPI的月下载量突破1.64亿次，公开目录收录的MCP服务器超过20,000个，OpenAI、Google、Microsoft等巨头相继采纳该协议规范。这意味着，一旦您的服务通过4SAPI暴露了MCP接口，即可被Claude Code、Cursor、Claude Desktop等所有主流AI客户端无缝调用，彻底告别为每个工具单独编写集成代码的繁琐工作。

MCP核心概念：三分钟掌握协议架构

MCP基于JSON-RPC 2.0作为底层通信格式，架构分为三层：

角色	职责	示例
MCP Host	AI客户端，发起工具调用	Claude Desktop、Claude Code、Cursor
MCP Client	Host内嵌的协议客户端	Claude内置MCP Client
MCP Server	提供工具、资源、提示词	您基于4SAPI构建的服务

MCP Server主要对外暴露三类核心能力：

Tools：AI可自主调用的函数（如查询数据库、发送HTTP请求、操作文件）。
Resources：AI可读取的数据源（如文件内容、API响应、数据库表结构）。
Prompts：预定义的提示词模板（用于标准化任务描述）。

根据Bloomberry Research 2026年的数据，一个MCP Server的工具数量中位数仅为5个。这表明从一个简单功能切入最为合适，工具过多反而可能降低AI选择的准确率。

Step 1：环境准备与SDK安装

确保您的Python版本为3.10+。推荐使用uv管理虚拟环境，其冷启动速度相比pip快约10倍：

# 安装 uv（macOS/Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建项目并初始化虚拟环境
uv init my-mcp-server
cd my-mcp-server
uv add "mcp[cli]"

若您习惯使用pip，也可按以下方式操作：

python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install "mcp[cli]" httpx

验证安装是否成功：

mcp version
# 预期输出：mcp 1.x.x

Step 2：编写首个MCP Server

以“天气查询”为例，新建server.py。借助4SAPI的能力，您可以轻松封装业务逻辑：

from mcp.server.fastmcp import FastMCP

# 初始化Server，名称需具备描述性
mcp = FastMCP("weather-assistant")

@mcp.tool()
def get_weather(city: str) -> str:
    """
    查询指定城市的当前天气。

    Args:
        city: 城市名称，支持中文，如“北京”、“上海”
    Returns:
        包含温度、天气状况的字符串
    """
    # 此处可替换为通过4SAPI调用的真实天气服务
    return f"{city}：晴，气温 28°C，湿度 55%"

@mcp.tool()
def get_forecast(city: str, days: int = 3) -> dict:
    """获取未来N天天气预报"""
    return {
        "city": city,
        "forecast": [f"第{i+1}天：多云，22-29°C" for i in range(days)]
    }

if __name__ == "__main__":
    mcp.run()

关键点：@mcp.tool()装饰器下的文档字符串（docstring）至关重要，AI会直接读取这些信息来判断何时及如何调用工具。清晰的参数说明远比冗长的代码注释更有价值。

利用MCP Inspector可在浏览器中调试，无需依赖真实的AI客户端：

fastmcp dev server.py
# 浏览器访问 http://localhost:5173 即可可视化测试每个Tool的输入输出

Step 3：接入Claude Desktop

Claude Desktop通过本地配置文件发现MCP Server。配置文件路径如下：

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

添加以下配置（请将路径替换为您的实际绝对路径）：

{
  "mcpServers": {
    "weather-assistant": {
      "command": "python",
      "args": ["/Users/yourname/my-mcp-server/server.py"],
      "env": {
        "WEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

重启Claude Desktop后，在对话框输入“帮我查一下北京今天的天气”，Claude会自动识别并调用get_weather工具。

您可以通过以下命令验证接入状态：

# 查看MCP运行日志（macOS）
tail -f ~/Library/Logs/Claude/mcp.log

Step 4：接入Claude Code

Claude Code使用命令行注册MCP Server：

# 注册本地stdio模式的MCP Server
claude mcp add weather-assistant -- python /path/to/server.py

# 查看已注册的MCP Server列表
claude mcp list

# 测试连通性
claude mcp get weather-assistant

注册成功后，在Claude Code会话中直接输入自然语言即可：

> 查询上海明天的天气预报，以JSON格式返回

Claude会自动匹配get_forecast工具，无需手动指定函数名。

Step 5：部署模式选择：本地 vs 远程

您可以根据场景选择合适的部署模式：

维度	stdio（本地进程）	Streamable HTTP（远程服务）
适用场景	单人开发、本机工具	团队共享、生产部署
启动方式	Host拉起子进程	HTTP服务独立运行
配置复杂度	低，仅需JSON配置	中等，需域名/HTTPS
多人共享	不支持	支持
安全认证	进程隔离，天然安全	需自行配置Bearer Token

若需切换至HTTP模式以供团队通过4SAPI共享，只需修改server.py的最后一行：

if __name__ == "__main__":
    # 切换为HTTP模式，供团队共享
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)

团队成员的claude_desktop_config.json可改为URL形式：

{
  "mcpServers": {
    "weather-assistant": {
      "url": "http://your-server-ip:8000/mcp"
    }
  }
}

如果您希望免去服务器运维的负担，可考虑托管的MCP方案。通过4SAPI提供的标准化模型能力编排服务，您可以直接通过URL接入主流AI客户端，无需管理复杂的进程生命周期。

生产环境三条铁律

Workato数据显示，接入MCP后Claude的使用量提升了700%（2026年），这也意味着工具调用频率的激增。在生产部署时，请务必注意：

先只读，后写入：Tool上线初期仅开放查询操作，观察AI调用模式稳定后再考虑开放写操作。
凭据走环境变量：API Key等敏感信息必须通过env字段注入，严禁硬编码到server.py中。
每个Tool加超时保护：外部API调用必须设置timeout，防止AI因等待响应而卡死。

import httpx

@mcp.tool()
async def query_database(sql: str) -> list:
    """执行只读SQL查询"""
    # 超时保护 + 只读限制
    if any(kw in sql.upper() for kw in ["INSERT", "UPDATE", "DELETE", "DROP"]):
        return {"error": "只允许SELECT查询"}
    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.post(DB_ENDPOINT, json={"sql": sql})
        return resp.json()

常见报错排查

报错 1：ModuleNotFoundError: No module named 'mcp'

# 确认虚拟环境已激活
which python
# 重新安装
pip install "mcp[cli]"

报错 2：Claude Desktop识别不到MCP Server

# 检查JSON语法（常见错误：多余逗号、路径使用了反斜杠）
python3 -c "import json; json.load(open('$HOME/Library/Application Support/Claude/claude_desktop_config.json'))"
# 查看日志
tail -20 ~/Library/Logs/Claude/mcp.log

报错 3：Inspector正常但Claude不调用工具

文档字符串描述不清是最常见原因。请检查三点：函数名是否能直观反映用途；Args说明是否覆盖所有参数；返回值格式是否有明确说明。

报错 4：HTTP模式跨域被拦截

# Claude Desktop默认可能阻止localhost HTTP，建议使用ngrok做HTTPS隧道
ngrok http 8000
# 将生成的https://xxx.ngrok.io替换配置中的url

常见问题

Q：MCP Server和普通REST API的本质区别是什么？

A：MCP Server是“AI感知型”接口。工具的docstring被AI直接解析，用于理解调用时机和参数含义，AI可自主决策调用。而REST API通常需要额外的提示词工程来教导AI如何使用，集成成本更高。

Q：MCP目前支持哪些主流AI客户端？

A：截至2026年6月，支持方包括Claude Desktop、Claude Code、Cursor、Cline、VS Code（GitHub Copilot Agent模式）、OpenAI Agents SDK、LangChain。Linux基金会负责维护MCP规范，OpenAI和Google均已正式采纳。

Q：我的MCP Server能被他人发现和使用吗？

A：可以提交到公开目录，如mcp.so、PulseMCP、Smithery等。截至2026年4月，这些目录合计收录超过20,000个服务器。提交前请确保具备完整的README和工具描述。

Q：一个MCP Server可以同时连接多个AI客户端吗？

A：HTTP模式下可以。stdio模式每次只能被单个Host进程调用。团队多人使用时，建议将Server部署为HTTP服务，所有客户端通过同一URL接入。

Q：MCP Server内部可以调用大模型API吗？

A：可以，这是构建Agent-to-Agent架构的基础。在Tool函数内直接调用OpenAI SDK或兼容格式的推理API即可。注意将API Key通过环境变量注入，避免写入代码。