1. 项目概述从“协议”这个词说起如果你在技术圈子里待过一段时间听到“协议”这个词脑子里可能会立刻蹦出 TCP/IP、HTTP、MQTT 这些老朋友。它们就像是数字世界里的“交通规则”和“外交辞令”规定了不同设备、不同软件之间如何打招呼、交换数据、处理异常。今天我们要聊的 MCP 协议也是这个大家族里的一员但它瞄准的场景和我们熟悉的那些网络协议有些不一样。简单来说MCPModel Context Protocol是一个专门为了让大型语言模型LLM能够安全、标准化地“使用”外部工具和数据源而设计的协议。你可以把它想象成给 AI 模型比如 Claude、GPT装上了一套标准化的“手”和“眼睛”。在没有 MCP 之前如果你想让你用的 AI 助手去查一下今天的股价、分析你本地的一个 Excel 表格或者控制你家的智能灯通常需要非常复杂的集成要么是 AI 厂商自己开发了某个特定功能比如联网搜索要么你需要写一堆胶水代码把 AI 的 API 和你自己的工具连接起来。这种方式不仅麻烦而且不通用换个模型或者换个工具就得重来一遍。MCP 的出现就是为了解决这个“连接”的痛点。它定义了一套简单的、基于 JSON-RPC 的通信规范。在这套规范里AI 模型作为客户端可以通过标准的“请求”向一个被称为MCP Server的后台服务“索要”能力。这个 Server 可以是你本地的一个 Python 脚本专门用来读取你电脑上的文件也可以是一个远程服务提供天气查询、数据库访问或者代码执行。关键在于只要这个 Server 按照 MCP 的协议格式“说话”任何支持 MCP 的 AI 客户端就都能“听懂”并使用它。所以当你在热搜词里看到 “MCP”、“Claude Code”、“MCP Server” 这些词频繁出现时背后反映的正是开发者们的一个强烈需求如何让自己心仪的 AI 编程助手如 Claude Code的能力突破沙箱安全、灵活地触达更广阔的真实世界数据和个人工作流。而“用装一次 MCP 的时间彻底搞懂它”这个标题正是想带你跳过晦涩的理论通过一次亲手搭建的实践把 MCP 的核心概念、工作流程和实际价值摸得门儿清。2. MCP 协议的核心设计思想与架构拆解要搞懂 MCP不能只停留在“它是连接 AI 和工具的桥梁”这个层面我们得钻进去看看这座桥是怎么设计的用了什么材料为什么要这么设计。这能帮助我们在后面自己搭建和调试时心里更有谱。2.1 为什么是 JSON-RPC协议层的选择MCP 选择 JSON-RPC 2.0 作为底层通信协议这是一个非常务实且关键的设计决策。JSON-RPC 是一种轻量级的远程过程调用RPC协议它用 JSON 格式来编码请求和响应。我们来看一个最简单的例子一个 AI 客户端想通过某个 MCP Server 执行一个加法计算它可能会发送这样的请求{ jsonrpc: 2.0, id: 1, method: tools/call, params: { name: calculator, arguments: { a: 5, b: 3 } } }对应的 Server 响应可能是{ jsonrpc: 2.0, id: 1, result: { content: [ { type: text, text: 8 } ] } }选择 JSON-RPC 有几个明显的好处人类可读易于调试所有通信内容都是结构化的文本你在开发时可以用眼睛看用print语句或者日志就能排查问题这比处理二进制协议要友好得多。语言无关性几乎所有的编程语言都有成熟的 JSON 解析和生成库。这意味着你可以用 Python、JavaScript、Go、Rust 等任何你熟悉的语言来编写 MCP Server客户端也可以用任何语言实现。生态成熟JSON-RPC 2.0 是一个很老也很稳定的标准有明确的规范定义错误处理、通知、批量请求等MCP 可以直接站在巨人的肩膀上不用重新发明轮子。适合流式交互虽然上面的例子是简单的请求-响应但 JSON-RPC 也支持“通知”没有id的请求和服务器主动推送这为未来 MCP 支持更复杂的异步交互比如长任务进度更新留下了空间。注意在实际的 MCP 实现中通信通常是通过标准输入输出stdio或 WebSocket 进行的。JSON-RPC 消息被编码成一行行的 JSON 文本以换行符分隔在这些通道上传输。这种设计使得 MCP Server 可以是一个简单的命令行程序极大地降低了开发门槛。2.2 核心概念资源Resources、工具Tools与提示词PromptsMCP 协议定义了三种核心的“能力”类型Server 可以向客户端“宣告”自己提供了哪些能力客户端则根据需要来调用。理解这三者就理解了 MCP 功能的骨架。资源Resources是什么可以理解为“只读的数据”。比如一个文件的内容、一个数据库的查询结果快照、一个网页的静态文本。资源有唯一的 URI 来标识例如file:///home/user/data.csv或weather://beijing/today。客户端如何用AI 客户端可以“读取”资源的内容。例如你可以让 Claude Code “去读一下/projects/plan.md这个文件”Claude Code 就会通过 MCP 向对应的 Server 发送读取该 URI 的请求然后将内容作为上下文喂给自己再基于此内容进行分析或回答。特点资源的内容在客户端请求时被获取并且通常是静态的或快照式的。MCP 协议还支持资源列表list和内容变更通知notify让客户端能发现和订阅资源更新。工具Tools是什么可以理解为“可执行的动作或函数”。这是 MCP 中最强大、最动态的部分。工具允许 AI 客户端去“做”一件事。比如“执行一段 Python 代码”、“在数据库中插入一条记录”、“发送一封邮件”、“重启服务器”。客户端如何用AI 客户端调用工具时需要提供工具所需的参数。Server 执行后将结果可能是文本、图片、错误信息返回。例如Claude Code 可以调用一个run_sql_query工具传入 SQL 语句获取查询结果。特点工具调用可能改变系统状态可能有副作用执行时间也可能较长。MCP 协议为工具调用定义了清晰的输入输出结构包括参数模式jsonSchema和错误处理。提示词Prompts是什么这是一种特殊的“模板”或“对话启动器”。Server 可以预定义一些高质量的提示词模板客户端可以获取这些模板并将其注入到与用户的对话中。客户端如何用比如一个项目管理工具的 MCP Server 可以提供一个名为 “generate_weekly_report” 的提示词。当用户在 AI 聊天界面输入“写周报”AI 客户端可以获取这个提示词模板里面可能包含了从 Server 获取当前任务列表的指令和报告格式然后基于这个模板生成更准确、更个性化的周报草稿。特点提示词是 MCP 中比较高级的特性它允许 Server 开发者不仅提供数据和动作还能提供“如何使用这些数据和动作的最佳实践指导”极大地提升了 AI 交互的智能性和流畅度。2.3 架构全景客户端、服务器与传输层让我们把上面这些概念串起来看看一次完整的 MCP 交互是如何发生的[AI 客户端 (如 Claude Code)] | | (通过 stdio/WebSocket 传输 JSON-RPC 消息) | [MCP 传输层] | | (初始化交换能力列表) | [MCP Server (如 文件系统Server、SQL Server)] | | (访问本地/远程数据与执行环境) | [真实世界 (文件、数据库、API)]启动与初始化AI 客户端启动一个 MCP Server 进程或连接到远程 Server。双方通过交换initialize和initialized握手。随后Server 会发送notify消息告知客户端自己提供了哪些resources、tools和prompts。这个过程叫做“能力宣告”。会话交互用户提问用户在 AI 客户端界面输入“帮我分析一下sales.xlsx里第三季度的数据趋势。”客户端决策Claude Code 理解用户意图发现需要读取一个文件并且可能需要执行计算。它检查已连接的 MCP Server 的能力列表发现有一个“文件系统 Server”能提供file://资源还有一个“Python 执行 Server”提供了execute_python工具。协议调用 a. Claude Code 向“文件系统 Server”发送read_resource请求URI 为file:///path/to/sales.xlsx。 b. 文件 Server 读取 Excel 文件可能将其内容以 CSV 文本或结构化 JSON 的形式返回。 c. Claude Code 拿到数据分析后发现需要做复杂计算于是向“Python 执行 Server”发送tools/call请求调用execute_python工具并将文件数据和计算逻辑作为参数传入。 d. Python Server 在安全环境中执行代码将计算结果返回。生成回复Claude Code 综合文件内容和计算结果生成最终的回答呈现给用户。安全与边界这是 MCP 设计的精妙之处。AI 客户端Claude Code本身并不直接拥有访问文件系统或执行代码的权限。它只是一个“调度员”和“解释员”。所有对真实世界的操作都通过 MCP Server 这个“代理”来完成。而 Server 的运行权限是由用户控制的。你可以决定让文件 Server 只能访问~/documents目录让 Python Server 运行在沙箱容器里。这样既扩展了 AI 的能力又将安全风险控制在可管理的、透明的范围内。3. 实战从零搭建一个 Excel 数据分析 MCP 环境理论讲得再多不如亲手做一遍。我们以热搜词中高频出现的Excel和Claude Code为场景目标是搭建一个能让 Claude Code 安全读取和分析我们本地 Excel 文件的 MCP 环境。你会用到uv这个快速的 Python 包管理工具同样是热搜词整个过程力求清晰。3.1 环境准备与工具选型首先明确我们的技术栈MCP 客户端我们将使用Claude Code。它是 Anthropic 公司为 Claude 模型打造的 IDE 插件原生支持 MCP 协议是我们体验 MCP 能力的绝佳窗口。MCP Server我们需要一个能提供“读取本地文件”能力的 Server。Anthropic 官方维护了一个高质量的 MCP Server 集合其中就包括mcp-server-filesystem。我们将用它。包管理/工具为了快速、干净地安装和运行 Python 环境的 MCP 组件我们选择uv。它比传统的 pip 更快能创建独立的虚拟环境非常适合这种工具类应用的部署。操作系统以 macOS/Linux 为例Windows 用户使用 WSL 或 Git Bash 也能获得类似体验。第一步安装 uv如果你的系统还没有 uv安装非常简单。打开终端执行# 使用官方安装脚本推荐 curl -LsSf https://astral.sh/uv/install.sh | sh安装完成后重启你的终端或者运行source ~/.bashrc或source ~/.zshrc来让 uv 命令生效。通过uv --version验证安装。实操心得uv 的安装脚本通常能自动处理路径问题。如果遇到uv: command not found请检查你的 shell 配置文件如~/.zshrc中是否添加了 uv 的 bin 目录路径。安装脚本最后输出的几行信息会告诉你路径添加到了哪里。第二步安装 Claude Code这取决于你使用的 IDE。VS Code直接在扩展商店搜索 “Claude Code” 并安装。JetBrains IDE (IntelliJ, PyCharm等)在插件市场搜索 “Claude Code” 并安装。 安装后通常需要登录你的 Claude 账户通常是 Anthropic 账号并授权。确保你使用的 Claude 模型版本如 Claude 3.5 Sonnet支持 MCP 功能。3.2 创建并配置 MCP Server我们不会从零写一个 Server而是使用官方现成的mcp-server-filesystem。但我们需要创建一个项目来管理它。创建项目目录并初始化mkdir my-mcp-excel-helper cd my-mcp-excel-helper uv init这会在当前目录创建一个pyproject.toml文件。安装 MCP Serveruv add mcp-server-filesystemuv 会自动处理依赖并将其安装到当前虚拟环境中。编写 Server 启动脚本 直接运行mcp-server-filesystem可能不够灵活我们创建一个简单的 Python 脚本来启动它并指定允许访问的目录这是安全配置的关键一步。 创建一个名为run_filesystem_server.py的文件#!/usr/bin/env python3 import anyio from mcp.server import Server from mcp.server.stdio import stdio_server import mcp.server.filesystem as fs import sys import os async def main(): # 1. 指定允许客户端访问的目录。 # 为了安全强烈建议限制在特定目录例如你的文档或项目文件夹。 # 这里我们允许访问当前用户的家目录~实际使用时应该更严格。 allowed_dirs [os.path.expanduser(~)] # 更安全的例子只允许访问特定项目文件夹 # allowed_dirs [/Users/yourname/Documents/ExcelFiles] # 2. 创建 Filesystem Server 实例 server Server() fs_server fs.create_filesystem_server(allowed_dirs) # 3. 将 Filesystem Server 的能力注册到主 Server server.add_resource_handlers(fs_server) server.add_tool_handlers(fs_server) # 这个 Server 主要提供资源文件读取工具可能较少 # 4. 通过标准输入输出运行 Server async with stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream, server.create_initialization_options()) if __name__ __main__: anyio.run(main)这个脚本的核心是allowed_dirs列表。务必将其修改为你真正想对 AI 开放的文件目录路径比如专门存放待分析 Excel 的文件夹。这是 MCP 安全模型的核心——权限由 Server 控制而 Server 由你配置。安装脚本依赖 脚本用到了anyio和mcp基础库我们需要安装uv add anyio mcp3.3 配置 Claude Code 连接 MCP Server现在我们需要告诉 Claude Code 去哪里找我们刚刚写的这个 Server。找到 Claude Code 配置位置 Claude Code 的配置通常以 JSON 文件形式存在。对于 VS Code 版本配置可能在以下位置之一全局配置~/.config/Claude/claude_desktop_config.json(macOS/Linux) 或%APPDATA%\Claude\claude_desktop_config.json(Windows)。或者直接在 VS Code 的设置中搜索 “Claude Code MCP”。最可靠的方法是查阅 Claude Code 的官方文档。但通常我们需要创建或编辑一个配置文件。创建配置文件 假设我们使用全局配置。在终端中# 创建配置目录如果不存在 mkdir -p ~/.config/Claude # 编辑配置文件 nano ~/.config/Claude/claude_desktop_config.json写入 MCP 配置 在配置文件中填入以下内容如果文件已存在请将mcpServers部分合并到顶层 JSON 对象中{ mcpServers: { my-local-files: { command: uv, args: [ --directory, /ABSOLUTE/PATH/TO/your/my-mcp-excel-helper, run, python, run_filesystem_server.py ] } } }重要替换将/ABSOLUTE/PATH/TO/your/my-mcp-excel-helper替换为你之前创建的项目目录的绝对路径。例如/Users/alice/projects/my-mcp-excel-helper。配置解析command: uv告诉 Claude Code 使用uv命令来启动 Server。args是传递给uv的参数。--directory指定 uv 的工作目录也就是我们的项目根目录这样 uv 才能找到正确的pyproject.toml和虚拟环境。runpythonrun_filesystem_server.py在指定目录的虚拟环境中运行我们的 Python 脚本。保存并重启 保存配置文件然后完全重启你的 VS Code或 JetBrains IDE。这是必须的因为 MCP Server 配置通常在启动时加载。3.4 验证与初体验让 Claude Code 读取 Excel重启 IDE 后打开 Claude Code 的聊天面板。如果配置正确Claude Code 会在后台自动启动我们配置的 MCP Server。你可以通过查看 IDE 的终端或日志输出如果有来确认。现在进行第一次测试准备一个 Excel 文件在你允许访问的目录如~/Documents/ExcelFiles/下创建一个简单的test.xlsx里面有一个名为“Sales”的工作表包含几行数据例如MonthRevenueCostJan100006000Feb120006500Mar150007000向 Claude Code 提问 在聊天框中输入“请读取并总结一下~/Documents/ExcelFiles/test.xlsx这个文件里 Sales 工作表的内容。”观察过程Claude Code 会理解你的指令识别出这是一个文件读取请求。它会通过 MCP 协议向my-local-filesServer 发送一个read_resource请求URI 大概是file:///Users/yourname/Documents/ExcelFiles/test.xlsx。我们的 Python Server 脚本接收到请求检查路径是否在allowed_dirs内如果在则读取该 Excel 文件。这里有一个关键点原始的mcp-server-filesystem可能默认将文件作为纯文本或二进制读取。对于 Excel直接读二进制数据对 AI 来说没用。一个更完善的 Server 应该集成pandas或openpyxl库将 Excel 文件解析成 CSV 或 JSON 格式再返回。这引出了 MCP Server 开发的核心理念Server 的职责是提供“友好”的数据接口。为了演示我们可以快速增强一下我们的 Server。修改run_filesystem_server.py在读取文件时判断后缀名并做处理这是一个简化示例生产环境需更健壮# ... 在文件读取处理逻辑部分通常需要修改或继承原Server的行为... # 注意此处为概念演示实际需深入修改 mcp-server-filesystem 的 handler # 更简单的做法是直接让AI读取CSV文件或使用专门处理Excel的MCP Server。 # 例如你可以安装社区版的 mcp-server-excel如果存在或者自己用 mcp 库和 pandas 写一个。鉴于时间我们调整目标让 Server 返回 Excel 文件的文本化表示例如通过pandas转为 CSV 字符串。这需要更定制化的 Server 开发超出了本次“快速上手”的范围。但核心流程你已经走通配置连接 - AI 发起请求 - Server 处理并返回 - AI 生成回答。一个更直接的验证方法是让 Claude Code 读取一个纯文本文件比如~/Documents/notes.txt。你可以输入“看看我的笔记文件~/Documents/notes.txt里写了什么。” 如果配置正确Claude Code 应该能准确读出文件内容。踩坑记录最常见的失败原因是路径问题。一是配置文件中的--directory参数必须是绝对路径。二是allowed_dirs配置的路径必须包含你想要访问的文件所在目录。三是 Claude Code 传递的 URI 是file://协议Server 需要正确地将 URI 路径转换为本地文件系统路径。如果遇到“资源未找到”错误请依次检查这三处。4. 深入MCP 的生态、高级模式与安全考量通过上面的实战你应该对 MCP 的基本工作流程有了切身感受。但 MCP 的潜力远不止于读取文件。让我们看看它的生态和更高级的玩法。4.1 丰富的 MCP Server 生态除了官方的文件系统 Server社区已经涌现出大量实用的 MCP Server这正是其生命力的体现。从你的热搜词里就能看到很多数据搜索类如tavily-mcp、brave-search-mcp。它们将网络搜索能力封装成 MCP 工具AI 可以调用它们进行实时信息检索弥补大模型知识截止日期的局限。开发者工具类chrome-devtools-mcp允许 AI 与 Chrome 开发者工具交互可用于自动化调试、分析页面性能。playwright-mcp/burp-mcp将浏览器自动化工具或安全测试工具的能力暴露给 AI。idapro-mcp连接反汇编工具 IDA Pro辅助进行二进制代码分析。专业软件集成类如cad-mcp、cesium-mcp旨在让 AI 能够与专业设计、地理信息系统软件进行有限交互。数据库与系统类sql-mcp服务器可以让 AI 直接查询数据库在严格权限控制下。理论上任何可以通过 CLI 或 API 控制的软件或服务都可以被包装成 MCP Server。如何查找和添加新的 Server通常这些 Server 会发布在 npmmodelcontextprotocol/server-xxx或 PyPImcp-server-xxx上。你可以用 uv 或 npm 安装它们。然后参照我们上面的配置方法在 Claude Code 的配置文件中为每个 Server 添加一个新的配置项指定对应的启动命令和参数。例如添加一个 Tavily 搜索 Server假设已通过uv add mcp-server-tavily安装{ mcpServers: { my-local-files: { ... }, web-search: { command: uv, args: [ --directory, /path/to/another/project, run, mcp-server-tavily ], env: { TAVILY_API_KEY: your_api_key_here } } } }注意很多 Server 需要 API 密钥等环境变量可以通过配置中的env字段传入。4.2 安全模型与权限边界再审视MCP 的安全哲学是“显式授权与沙箱化”。这是它能否被企业或个人放心使用的基石。权限最小化原则每个 MCP Server 都应该只拥有完成其特定任务所需的最小权限。我们的文件 Server 只读特定目录一个数据库 Server 可能只拥有某个只读用户的凭证一个代码执行 Server 必须运行在隔离的容器或沙箱中。Server 即信任边界用户信任的是MCP Server 的代码和配置而不是 AI 模型本身。AI 模型只是发送符合协议的请求。因此选择或编写 MCP Server 时必须审慎检查其代码。不要运行来源不明或权限要求过高的 Server。传输安全对于本地 stdio 通信数据在进程间传递相对安全。对于网络 WebSocket 连接务必使用wss://SSL/TLS并验证身份防止中间人攻击。输入验证与清理Server 端必须对来自 AI 客户端的输入进行严格的验证。例如一个文件路径参数必须检查是否包含..等路径遍历序列并确保最终路径落在allowed_dirs内。一个 SQL 工具在真正执行前可能需要对查询语句进行严格的语法检查或限制例如禁止DROP,DELETE等语句。给你的安全清单[ ] 我是否审查了所使用 MCP Server 的源代码[ ] 我为每个 Server 配置的权限是否是其功能所需的最小权限如文件访问范围、数据库用户权限[ ] 我是否使用了最新版本的 Server 和客户端以获取安全更新[ ] 对于网络 Server我是否使用了加密连接TLS[ ] 我是否定期检查 Claude Code 等客户端连接的 MCP Server 列表移除非必要的 Server4.3 调试与问题排查实战指南当你搭建的 MCP 环境不工作时可以按照以下步骤排查这比盲目搜索更高效。问题一Claude Code 完全没有反应好像没连接上 Server。检查点1配置文件语法和路径使用jsonlint或在线工具检查你的claude_desktop_config.json文件格式是否正确。绝对路径确保--directory参数中的路径是绝对路径并且该路径下确实有pyproject.toml和你的 Server 脚本。命令可用性确保uv命令在系统的 PATH 中。可以在终端中手动执行配置文件中完整的command和args看能否成功启动 Server。例如uv --directory /ABSOLUTE/PATH/TO/project run python run_filesystem_server.py如果这里就报错如模块找不到说明 Server 环境有问题。检查点2查看客户端日志Claude Code 通常会有日志输出位置。在 VS Code 中可以打开“输出”面板View-Output然后选择 “Claude Code” 或 “MCP” 相关的日志通道。这里会显示连接 Server、初始化、发送请求等详细信息是排查问题的第一手资料。问题二Claude Code 能连接但读取文件时提示“资源未找到”或“权限被拒绝”。检查点1Server 的allowed_dirs配置确认你请求的文件路径如~/Documents/test.xlsx的完整展开路径如/Users/you/Documents/test.xlsx是否包含在allowed_dirs列表中的某个目录或其子目录下。allowed_dirs配置的是前缀请求的路径必须以此前缀开头。检查点2文件路径的 URI 转换Claude Code 发送的 URI 是file:///Users/you/Documents/test.xlsx。你的 Server 需要正确地将file://URI 转换为本地路径。mcp-server-filesystem应该处理了这一点但如果你自己写 Server这里容易出错。检查点3文件系统真实权限运行 Claude Code 和 MCP Server 进程的用户是否有操作系统的权限去读取那个文件可以用ls -l命令检查文件权限。问题三Server 进程意外退出或挂起。检查点1Server 脚本的异常处理你的run_filesystem_server.py是否捕获了可能出现的异常如果没有一个未处理的异常如导入错误、权限错误会导致进程崩溃。在开发时可以在脚本开头添加更详细的日志记录或将错误信息打印到标准错误输出stderr这些信息有时会被客户端捕获并显示在日志里。检查点2资源清理确保在 Server 的async with块或finally块中正确关闭了打开的文件、数据库连接等资源。通用调试技巧独立测试 Server在配置到 Claude Code 之前先写一个简单的测试客户端脚本用 stdio 连接你的 Server手动发送 JSON-RPC 请求看响应是否正常。这能帮你快速定位是 Server 逻辑问题还是客户端集成问题。启用详细日志查阅你所使用的 MCP Server 和 Claude Code 的文档看是否有启用调试或详细日志的选项。5. 超越基础构建自定义 MCP Server 解锁专属工作流当你熟悉了使用现成的 Server 后很自然地会想能不能为我自己的工具或数据源写一个 MCP Server答案是肯定的这也是 MCP 最激动人心的地方。下面我们以一个简单的“待办事项列表Todo List管理 Server”为例勾勒出开发一个自定义 Server 的轮廓。5.1 定义能力我们想提供什么假设我们有一个简单的命令行待办事项应用数据存在本地的todos.json文件里。我们想通过 MCP 让 Claude Code 也能管理它。我们计划提供以下能力资源todo://list获取所有待办事项的列表只读。工具add_todo添加一个新的待办事项参数title,description?。mark_todo_done将一个待办事项标记为完成参数id。delete_todo删除一个待办事项参数id。5.2 使用 Python MCP SDK 快速搭建Anthropic 提供了官方的 Python SDKmcp它大大简化了 Server 的开发。首先在新项目中安装uv init my-todo-server cd my-todo-server uv add mcp然后创建server.pyimport anyio from mcp import Server, types import json import os from pathlib import Path from typing import List, Optional # 模拟数据存储 TODO_FILE Path.home() / .my_todos.json def load_todos() - List[dict]: if not TODO_FILE.exists(): return [] with open(TODO_FILE, r) as f: return json.load(f) def save_todos(todos: List[dict]): with open(TODO_FILE, w) as f: json.dump(todos, f, indent2) async def main(): # 初始化 Server server Server(my-todo-server) # 1. 定义资源待办事项列表 server.list_resources() async def handle_list_resources() - List[types.Resource]: # 返回我们提供的资源列表这里只有一个资源 return [ types.Resource( uritodo://list, nameTodo List, descriptionThe full list of todo items., mimeTypeapplication/json ) ] server.read_resource() async def handle_read_resource(uri: str) - types.ReadResourceResult: # 当客户端请求读取 todo://list 时返回数据 if uri todo://list: todos load_todos() # 将数据转换为 MCP 要求的 Content 格式 return types.ReadResourceResult( contents[ types.TextContent( typetext, textjson.dumps(todos, ensure_asciiFalse) ) ] ) raise ValueError(fUnknown resource: {uri}) # 2. 定义工具添加待办 server.list_tools() async def handle_list_tools() - List[types.Tool]: return [ types.Tool( nameadd_todo, descriptionAdd a new todo item., inputSchema{ type: object, properties: { title: {type: string, description: The title of the todo.}, description: {type: string, description: Optional description.} }, required: [title] } ), # ... 类似地定义 mark_todo_done 和 delete_todo 工具 ] server.call_tool() async def handle_call_tool(name: str, arguments: dict) - types.CallToolResult: if name add_todo: todos load_todos() new_id max([t.get(id, 0) for t in todos], default0) 1 new_todo { id: new_id, title: arguments[title], description: arguments.get(description, ), done: False } todos.append(new_todo) save_todos(todos) return types.CallToolResult( content[ types.TextContent( typetext, textfTodo added successfully with ID: {new_id} ) ] ) # ... 处理其他工具调用 raise ValueError(fUnknown tool: {name}) # 3. 通过 stdio 运行 Server async with await anyio.connect_process( [python, -u, -m, mcp.cli, run, --server, __file__], stdinanyio.process.PIPE, stdoutanyio.process.PIPE, stderranyio.process.STDERR, ) as (stdin, stdout, _): await server.run(stdin, stdout) if __name__ __main__: anyio.run(main)这个示例展示了 MCP Server 的核心结构使用装饰器注册资源列表、资源读取、工具列表和工具调用的处理器。SDK 帮你处理了 JSON-RPC 的编解码和协议流程你只需要关注业务逻辑。5.3 配置与测试你的自定义 Server开发完成后和之前一样将你的 Server 配置到 Claude Code 中{ mcpServers: { my-todo-list: { command: uv, args: [ --directory, /ABSOLUTE/PATH/TO/my-todo-server, run, python, server.py ] } } }重启 Claude Code然后你就可以尝试说“帮我用我的待办事项列表添加一个‘写 MCP 博文’的任务。” Claude Code 会识别出add_todo工具并调用你的 Server 来执行。通过这个例子你可以看到任何你能用代码操作的东西——本地文件、数据库、智能家居 API、内部业务系统——都可以通过编写一个 MCP Server 来让 AI 助手安全、受控地访问。这为 AI 融入个人和企业的个性化工作流打开了无限可能。从安装配置一个现成的 Server到理解其协议原理再到亲手打造一个属于自己的 Server这条路径正是深入掌握 MCP 协议的最佳实践。它不再是一个抽象的概念而是一个你可以实实在在用来提升效率的杠杆。