从零开始构建 Python MCP 服务器

从零开始构建 Python MCP 服务器

Model Context Protocol (MCP) 现在已成为行业标准。其 SDK 月下载量已达到 9700 万次。几乎所有主流 AI 工具都在使用它。大多数指南只教你如何安装现有的服务器。本指南将教你如何使用 Python 和 GitHub API 构建自己的服务器。

什么是 MCP？

它是一种允许 AI 客户端调用外部服务的协议。你的服务器负责处理来自 Claude 或 Cursor 等工具的请求。

MCP 的三个核心部分：

• 工具 (Tools)：AI 调用以执行操作或获取数据的函数。
• 资源 (Resources)：只读数据端点，例如文件或数据库记录。
• 提示词 (Prompts)：用于保持工作流一致性的可重用指令模板。

设置你的项目

创建一个目录并使用 uv 安装必要的库：

mkdir github-mcp-server
cd github-mcp-server
uv init .
uv add "mcp[cli]" httpx

构建服务器

使用 FastMCP 来处理繁重的工作。一个优秀的 MCP 服务器通常包含三个特定文件：server.py、pyproject.toml 以及一个用于存放 GitHub token 的可选 .env 文件。

开发专业技巧：

• 为工具返回值使用 Pydantic 模型。这能为 AI 提供结构化数据，而不是杂乱的字符串。
• 编写清晰的 docstrings。AI 会通过阅读这些内容来决定何时使用你的工具。
• 对数值输入进行限制 (Clamp)。AI 模型经常会发送像 0 或 100 这样出乎意料的数字。
• 处理异常。服务器崩溃可能会导致整个连接中断。

测试与部署

不要等到在 Claude 中测试时才动手。先使用 MCP Inspector。运行： uv run mcp dev server.py

这将在 http://localhost:5173 打开一个本地界面。你可以在一处测试工具、资源和提示词。

连接到 Claude Desktop： 更新你的配置文件以包含你的服务器。使用 server.py 文件的完整路径。务必使用 uv run 而不是直接使用 python 命令，以避免环境错误。

连接到 Claude Code： 使用 CLI 命令： claude mcp add github-tools -- uv run python /path/to/server.py

构建自定义 MCP 服务器可以让你将实时数据引入 AI 工作流中。

Source: https://dev.to/moksh/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide-397k

Optional learning community: https://t.me/GyaanSetuAi