30行Python自建MCP服务器并接入Claude Code

MCP是什么：AI应用的USB-C接口

MCP全称Model Context Protocol，是一个把AI应用连接到工具和数据的开放标准。原视频用了一个很贴切的比喻：它就像AI世界的USB-C接口，一种插头形状，适配各种设备。

这个协议里有三种角色。Host是AI应用本身，比如Claude Code；Host内部有一个MCP client，负责维持与各个server之间的连接；而我们今天要写的部分是server——它把工具暴露出来，任何支持MCP的应用都能即插即用。换句话说，写一次，处处可用。

MCP的角色分工

这解决了上一期留下的问题：所有财务工具都挤在一个Python脚本里，只有那一个agent能用。包成MCP server之后，工具的使用范围一下子打开了。

MCP 由 Anthropic 于 2024 年底发布并开源，采用 JSON-RPC 2.0 作为消息格式，因此不同语言、不同平台实现的 client 与 server 之间可以互通。协议定义了初始化握手、能力协商、工具调用、资源读取、提示获取以及通知等标准消息类型。除本文用到的 Python SDK 外，官方还提供 TypeScript SDK，社区也有 Go、Java、Rust 等实现。由于是开放协议而非某家厂商的私有接口，社区已经积累了文件系统、数据库、浏览器、Git 仓库等大量现成 server，可以直接复用。

服务器能提供什么：Tools、Resources、Prompts

一个MCP server可以对外提供三类内容：

Tools：模型可以调用的函数，会执行代码或产生动作，也就是第三期里用过的类型。
Resources：应用可以直接加载进上下文的数据，每个都有自己的地址，类似文件。
Prompts：可复用的模板，用户自己挑选；在Claude Code里它们会显示为斜杠命令。

本文的财务服务器三类都会提供，这也是理解MCP能力边界的最好方式——Tools是"让模型做事"，Resources是"给模型看数据"，Prompts是"帮用户组织请求"。

三类能力在控制流上有本质区别：Tools 由模型自主决定是否调用，调用前通常需要用户批准，因为可能产生副作用；Resources 由应用或用户选择加载，模型并不主动读取，适合放预算表、配置文件这类只读数据；Prompts 由用户显式触发，常用于把固定流程包装成一键操作。设计 server 时，把会改变状态的操作放进 Tools，把只读数据放进 Resources，能让权限边界更清晰，也便于应用层做审批与审计。

动手写：装饰器、类型提示和docstring

先安装官方Python SDK：pip install mcp，记得带上cli-extra，并且需要Python 3.10或更新版本。

一个容易踩的坑：SDK进入第2版后，server类改名为mcp-server，老教程里还叫fast-mcp。导入mcp-server并创建一个名为finance的服务器，这一行代码就已经是一个能跑的服务器了。

SDK版本变化带来的命名差异

接下来往里加东西。以get-spending工具为例，它就是一个普通的Python函数，加上mcp.tool装饰器。SDK会根据类型提示自动构建输入schema：category和month变成必填的字符串字段；因为category是Literal类型，schema里会自动生成enum，取值为food、rent或transport。函数的docstring会变成工具描述，所以和第三期一样，描述要写得清晰详细。函数返回一个字典，SDK会把它作为工具结果回传给Claude。

Resource用mcp.resource装饰器声明，给它一个地址，比如budgets://current，应用就能直接把它加载进上下文，不需要模型先调用工具。

用装饰器声明资源地址

Prompt则定义monthly review，接收一个month参数，返回一段现成的请求交给Claude。

最后调用mcp.run。默认走标准输入输出，也就是stdio传输：应用把脚本作为本地进程启动，双方通过它的输入输出交换消息。

stdio 与 streamable HTTP 是 MCP 的两种传输方式。stdio 下，host 把 server 脚本作为子进程启动，双方通过标准输入输出按行交换 JSON-RPC 消息，适合本地工具，进程随应用退出而结束。streamable HTTP 下，server 作为独立服务监听端口，host 通过 URL 连接，支持多客户端共享和远程部署，并可借助 SSE 实现服务端推送。选择哪种传输主要取决于工具是否需要跨机器共享、是否需要长期运行，与工具本身的实现无关。

先自测再接入：Inspector与mcp add

在连接Claude之前，先单独测服务器。用mcp-dev加上服务器文件运行，浏览器里会打开MCP inspector。它能列出我们的两个工具、一个resource和一个prompt。用food和October调用get-spending，结果是花了620、预算500——超支了。有任何问题，在模型介入之前就能在这里发现。

在Inspector中验证工具返回结果

接入命令是claude mcp add，先写名字，然后两个短横线，后面跟着启动服务器的命令。两个短横线之后的所有内容就是Claude Code要执行的命令；不加transport参数意味着这是一个本地stdio服务器。运行claude mcp list，看到connected就说明连上了。

启动Claude Code，直接问"我本月food类别超预算了吗？"，首次调用需要批准。这次调用会带上我们服务器的名字作为标记，一眼就能看出答案来自你自己的数据。

作用域值得留意：默认只为当前项目添加服务器；加scope user可以在所有项目中使用；scope project则会写出一个.mcp.json文件，可以提交到仓库，队友首次运行时批准即可。

想走网络而不是本地进程，就用streamable HTTP传输运行服务器，再用transport http加URL的方式添加。

还有一个实用提醒：每个已连接服务器的工具都会在每次会话中加载并占用上下文，所以工具列表要保持精简聚焦。

核心要点回顾

MCP是连接AI应用与工具、数据的开放标准；server提供tools、resources、prompts三类能力；借助mcp.server、装饰器、类型提示和docstring，大部分工作由SDK自动完成；先用inspector验证，再用claude mcp add接入。下一期将用Claude Agent SDK构建agent，用的是驱动Claude Code的同一套引擎。