用 Python、Docker 和 Claude Code 构建 MCP 服务器完整教程

每个 MCP 教程都遵循相同的基本脚本：构建服务器，指向 Claude Desktop，截图聊天窗口，完成。如果你想做个演示，这很好。但如果你想构建可以交付、在面试中展示或交给其他开发者的东西，这就不够了。

本文将带您完成在 Python 中构建 MCP 服务器、用 Docker 容器化并将其连接到 Claude Code 的完整过程——全部从终端完成，无需 GUI。

您将构建什么

到本教程结束时，您将拥有：

• 一个 Python MCP 服务器，向任何兼容 MCP 的 AI 客户端暴露自定义工具
• 一个 Docker 容器，将服务器打包以实现可重现的部署
• Docker 容器与终端中 Claude Code 之间的工作连接
• 对涉及的安全风险的理解以及如何缓解最严重的问题

我们构建的服务器是一个项目脚手架工具。您给它一个项目名称和语言，它会生成带有正确文件的起始目录结构。它简单到可以在一个下午构建，但又实用到可以真正放在简历上。

什么是 MCP（为什么您应该关心）？

Model Context Protocol (MCP) 是一个开放标准，让 AI 模型可以连接到外部工具和数据源。Anthropic 于 2024 年 11 月发布，一年内就成为扩展 LLM 能力的默认方式。OpenAI 于 2025 年 3 月采用，Google DeepMind 于 4 月跟进。该协议现在每月有超过 9700 万次 SDK 下载和超过 10,000 个活跃服务器。

思考 MCP 最简单的方式是将其视为 AI 的 USB-C 接口。在 MCP 之前，每个 AI 提供商都有自己的工具调用方式。OpenAI 有函数调用，Google 有自己的格式。如果您想让工具与多个模型一起工作，必须多次实现。MCP 为您提供一个在任何地方都有效的接口。

为什么选择 Claude Code 而不是 Claude Desktop？

大多数 MCP 教程使用 Claude Desktop 作为客户端。这可行，但 Claude Code 对开发者有一些优势：

• 它存在于您的终端中——无需配置 GUI，无需在隐藏配置目录中手动编辑 JSON 文件
• 它已经在您编码的地方——在同一个终端会话中编写、测试和连接服务器，减少上下文切换
• 它适用于无头机器——如果您 SSH 到开发机器或在 CI 中运行，Claude Desktop 不是选项，但 Claude Code 是

步骤 1：构建 MCP 服务器

我们使用 FastMCP，一个 Python 框架，处理所有协议管道，让您可以专注于工具。创建新项目目录并设置：

mkdir mcp-scaffolder && cd mcp-scaffolder
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]>=1.25,<2"

为什么要固定版本？MCP Python SDK v2.0 正在开发中，将显著改变传输层。固定到 >=1.25,<2 让您的服务器保持工作，直到您准备好迁移。

步骤 2：本地测试

在 Docker 化之前，确保服务器实际工作：

# 快速烟雾测试 - 服务器应该启动无错误
python server.py

您应该看到……什么都没有。这是正确的。通过 stdio 的 MCP 服务器只是坐在那里等待 stdin 上的 JSON-RPC 消息。按 Ctrl+C 停止它。

对于适当的测试，使用 MCP Inspector（Anthropic 的调试工具）：

npx @modelcontextprotocol/inspector python server.py

这会打开一个 Web 界面，您可以在其中查看工具、手动调用它们并检查来回传递的 JSON-RPC 消息。

步骤 3：Docker 化

在项目根目录创建 Dockerfile：

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY server.py .
ENV PYTHONUNBUFFERED=1
CMD ["python", "server.py"]

创建 requirements.txt：

mcp[cli]>=1.25,<2

构建并验证：

docker build -t mcp-scaffolder .
docker run -i mcp-scaffolder

Dockerfile 中重要的两点：

• PYTHONUNBUFFERED=1 至关重要——没有它，Python 缓冲 stdout，MCP 客户端可能挂起等待响应
• docker run -i（交互模式）是必需的——-i 标志保持 stdin 打开，让 MCP 客户端可以发送消息到容器

步骤 4：连接到 Claude Code

现在将 Docker 容器连接到 Claude Code：

claude mcp add scaffolder -- docker run -i --rm mcp-scaffolder

这就是整个命令。验证它已注册：

claude mcp list

您应该在输出中看到 scaffolder，传输类型为 stdio。

步骤 5：使用它

在 Claude Code 中，尝试：

创建一个名为"weather-api"的新 Python 项目

Claude Code 应该发现您的 scaffold_project 工具，使用 name="weather-api" 和 language="python" 调用它，并报告创建了什么。检查文件系统，您应该看到完整的项目结构。

安全：其他教程遗漏的内容

这是大多数 MCP 教程跳过的部分。MCP 有真实的安全事件，不是理论上的。理解它们让您成为更好的开发者。

提示注入问题

MCP 服务器根据 LLM 的决定在您的机器上执行代码。如果攻击者可以影响 LLM 看到的内容，他们可以影响服务器的行为。这称为提示注入，是 MCP 生态系统中头号未解决的安全问题。

2025 年 5 月，Invariant Labs 的研究人员对官方 GitHub MCP 服务器展示了这一点。他们创建了一个恶意 GitHub issue，当 AI 代理读取时，劫持代理将私有仓库数据（包括薪资信息）泄露到公共拉取请求中。根本原因是过于宽泛的个人访问令牌与不受信任的内容落入 LLM 上下文窗口相结合。

真实的 CVE，不是理论

• CVE-2025-6514：mcp-remote 中的严重命令注入漏洞，437,000+ 环境使用
• CVE-2025-6515：oatpp-mcp 中的会话劫持，通过可预测的会话 ID
• MCP Inspector RCE：Anthropic 自己的调试工具允许未经身份验证的远程代码执行

您实际应该做什么

1. 限制文件系统访问——仅挂载需要的特定目录，切勿挂载 / 或 ~
2. 验证所有输入——检查路径遍历攻击，如 name="../../etc/passwd"
3. 使用最小权限令牌——给予 MCP 服务器需要的最小权限
4. 不要从不受信任的源安装 MCP 服务器——像对待任何在您的机器上以您的权限运行的代码一样谨慎对待 MCP 服务器包

总结

我们用 FastMCP 构建了 Python MCP 服务器，用 Docker 容器化，并将其连接到 Claude Code。整个东西适合约 100 行 Python、六行 Dockerfile 和一个 claude mcp add 命令。

MCP 生态系统是真实的且增长迅速。该协议得到 Anthropic、OpenAI 和 Google 的支持。它现在由 Linux 基金会管理。但它也很年轻，安全故事仍在书写。用它构建，但要睁大眼睛构建。

YUANLEISVIP

收藏 链接