MCP开发-01.从0开发一个MCP

发表于 | 分类于
用 Python FastMCP 从零实现一个最小 MCP 工具服务：环境、stdio 配置、排错与可选的 Streamable HTTP。

概念篇： MCP 是什么 → 本文（实践篇）

目标与环境

从 0 做一个能被 LLM 调用的 MCP，可以概括成三件事：

  1. 用 SDK 写一个 Server，至少暴露一个 Tool。
  2. 在本地或服务器上 常驻或按需启动 该进程（传输方式见下文）。
  3. 在 MCP Host（Cursor、Claude Desktop、Trae 等）里写入配置，让客户端能发现并调用工具。

环境与依赖

项 说明
Python 建议 3.10+，以 python-sdk 当前要求为准。
安装 SDK pip install "mcp[cli]"；团队若用 uv，可用 uv add mcp 或 uv run。
虚拟环境 建议单独 venv，客户端里 command 指向该环境的 python，避免装到全局却用错解释器。
心智模型（排错时有用）： 一块是 协议与进程（如何被拉起、stdio/HTTP、消息收发）；一块是 业务逻辑（参数、算法、读写文件与 API）。先跑通 stdio + 单工具，再考虑远程与工程化。

步骤一 最小代码

下面用 FastMCP 暴露一个工具：两整数相加。函数名避免使用 sum，以免遮蔽 Python 内置函数。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from mcp.server.fastmcp import FastMCP
# 名称与客户端配置里的服务名对应，便于识别
mcp = FastMCP("sum_int_tool")
@mcp.tool()
def add_ints(a: int, b: int) -> int:
    """两整数相加。
    Args:
        a: 整数 a
        b: 整数 b
    Returns:
        两数之和
    """
    return a + b
if __name__ == "__main__":
    # stdio：由 Host 以子进程启动本脚本，经标准输入输出通信；一般不需要 host/port
    mcp.run(transport="stdio")
  • Docstring 与 类型注解 会参与工具元数据，影响模型何时、如何传参。
  • mcp.run(...) 会阻塞；不要用在其后的 print 当作「启动成功」日志，排错请看 排错与调试思路。

步骤二 stdio 配置

配置示例

在支持 MCP 的工具里，stdio 模式通常写「可执行文件 + 参数」，由 Host 拉起子进程。下面仅为结构示例；字段名、是否嵌套 mcpServers 因产品而异，请以当前版本的官方文档为准。

1
2
3
4
5
6
7
8
9
{
  "mcpServers": {
    "sum_int_tool": {
      "command": "python",
      "args": ["D:\\gitlab_sync\\MCP\\0.demo.py"],
      "autoApprove": []
    }
  }
}
  • 路径：换成你保存上述 .py 的本机路径；若在 JSON 里含反斜杠，注意转义或使用正斜杠。
  • 解释器：command 建议改为虚拟环境中 Python 的绝对路径，避免与终端里 pip install mcp 的环境不一致。
  • 安全：autoApprove 是否自动批准工具调用因客户端而异；生产或敏感环境应了解其含义后再改。
    配置成功后，在工具/插件面板中应能看到服务已连接。
    配置示例

试用

在对话中明确要求使用 MCP 工具计算两数之和，确认调用了 sum_int_tool。
调用示例

步骤三 HTTP（可选）

概念对照见：传输方式概要。

  • stdio：本机、由 Host 拉起，最常见于 IDE/桌面端。
  • Streamable HTTP（及兼容场景下的 SSE）：需要独立地址、多机或网关时；新规范侧更推荐 Streamable HTTP。
    入口里只保留一种 mcp.run，不要连续写两次：
1
2
3
if __name__ == "__main__":
    # mcp.run(transport="stdio")
    mcp.run(transport="streamable-http")

客户端侧通常改为填写 URL（例如 http://127.0.0.1:8000/mcp，具体路径以 SDK 默认与日志为准），而不是 command + args。部署时可查阅 SDK 中的 stateless_http、json_response 等参数。

用 Inspector 自测 HTTP 服务

服务在本机以 HTTP 跑起来后，可用官方工具验证连接（命令以当前文档为准）：

1
npx -y @modelcontextprotocol/inspector

在 Inspector 界面中填入 MCP 端点 URL 进行连接与工具调用测试。

排错与调试思路

现象 可检查项
Host 显示未连接 command / args 是否指向正确脚本；JSON 语法、路径转义；该 Python 是否已 pip install mcp。
模型不调工具 提示词是否明确要求使用工具；工具名与描述是否清晰；部分客户端需手动开启/授权工具。
仅 HTTP 不通 防火墙、端口、URL 路径是否与服务器监听一致；是否混用了 stdio 配置格式。
调试时优先区分：进程有没有被拉起 → 协议是否握手成功 → 工具列表是否出现 → 单次调用参数与返回值。

小结与延伸

阶段 要点
开发 FastMCP + @mcp.tool()，docstring 与类型写清楚
本地 stdio transport="stdio" + Host 里配置子进程命令与参数
远程 streamable-http（或兼容场景下的 SSE）+ URL
延伸阅读： MCP Python SDK · 协议官网（Tools / Resources / Prompts 等完整能力）
-------------本文结束感谢您的阅读-------------