2026年MCPModel Context Protocol已成为AI Agent工具集成的标准协议。本文从零搭建一个完整的MCP Server文件系统操作Web搜索并集成到Claude Code和Cursor中全程实战代码可运行。关键词MCP协议、AI Agent、MCP Server、Python、Claude Code、Cursor、Model Context Protocol一、为什么AI Agent需要MCP1.1 从笼中大脑说起AI Agent的智能被困在LLM内部——LLM再聪明也无法直接读取你的文件、搜索网页、操作数据库。要让AI真正动手干活必须给它接上外部世界的接口。1.2 碎片化的工具集成方案在MCP出现之前AI工具集成的方案是碎片化的方案问题OpenAI Function Calling每家模型各一套不通用LangChain Tools框架锁定不支持跨平台IDE私有插件系统各有各的插件格式核心痛点AI工具每对接一个外部能力就要写一套适配代码。1.3 MCP的USB-C隐喻2024年11月Anthropic提出了MCPModel Context Protocol定位为AI应用的USB-C接口——就像USB-C统一了各种充电口MCP统一了AI工具的能力接口。核心理念一次开发到处可用。同一个MCP Server可以即插即用地接入Claude Code、Cursor以及任何支持MCP的AI工具。二、MCP协议核心原理2.1 三大原语MCP采用客户端-服务器架构Server通过三大原语暴露能力原语作用类比到HTTPTool暴露可执行的操作读文件、搜索、查DBPOST请求Resource提供结构化数据读取文件内容、系统状态GET请求Prompt可复用的交互模板预定义请求体2.2 传输层MCP支持三种传输方式传输方式适用场景stdio本地子进程低延迟适合CLI工具集成SSE远程服务适合跨网络调用Streamable HTTPv1.2新增支持长时间运行任务2.3 生命周期初始化Client与Server能力协商capabilities交换操作Client调用Tool、读取Resource、使用Prompt关闭优雅关闭释放资源三、MCP Server架构设计Python SDK提供两种构建方式Server类底层API直接操作Request/Response精细控制FastMCP封装高阶API基于Python decorator一行代码注册一个Tool推荐大部分场景用FastMCP自动处理Schema生成、消息路由、JSON-RPC序列化。四、Python实战从零搭建MCP Server4.1 环境准备# 创建项目 mkdir mcp-server-demo cd mcp-server-demo python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装依赖 pip install mcp httpx4.2 基础Server骨架from mcp.server.fastmcp import FastMCP server FastMCP(MyAssistant) server.on_startup() async def startup(): print(Server started!) server.on_shutdown() async def shutdown(): print(Server shutting down...) if __name__ __main__: server.run(transportstdio)4.3 实现Tool文件系统操作import os from pathlib import Path from mcp.types import TextContent server.tool() async def read_file(path: str) - list[TextContent]: 读取指定文件的内容。 try: content Path(path).read_text(encodingutf-8) return [TextContent(typetext, textcontent)] except FileNotFoundError: raise McpError(f文件不存在: {path}) except Exception as e: raise McpError(f读取文件失败: {str(e)}) server.tool() async def write_file(path: str, content: str) - list[TextContent]: 将内容写入指定文件。 try: Path(path).write_text(content, encodingutf-8) return [TextContent(typetext, textf成功写入文件: {path})] except Exception as e: raise McpError(f写入文件失败: {str(e)}) server.tool() async def list_directory(path: str .) - list[TextContent]: 列出指定目录的内容。 try: items os.listdir(path) return [TextContent(typetext, text\n.join(items))] except FileNotFoundError: raise McpError(f目录不存在: {path})4.4 实现ToolWeb搜索import httpx server.tool() async def web_search(query: str, max_results: int 5) - list[TextContent]: 搜索网页内容返回搜索结果摘要。 search_url https://api.duckduckgo.com/ params { q: query, format: json, no_html: 1, skip_disambig: 1, } async with httpx.AsyncClient(timeout10.0) as client: try: response await client.get(search_url, paramsparams) response.raise_for_status() data response.json() results [] for item in data.get(RelatedTopics, [])[:max_results]: if Text in item and FirstURL in item: results.append(f- {item[Text]}\n {item[FirstURL]}) if not results: return [TextContent(typetext, textf未找到相关结果)] return [TextContent(typetext, text\n\n.join(results))] except httpx.TimeoutException: raise McpError(搜索请求超时)4.5 实现Resource系统状态import platform server.resource(system://status) async def system_status() - str: 获取系统运行状态信息。 info [ f系统: {platform.system()} {platform.release()}, f架构: {platform.machine()}, fPython: {platform.python_version()}, ] return \n.join(info)4.6 实现Prompt操作模板server.prompt() def search_analysis(query: str) - str: 搜索分析模板先搜索再分析结果。 return f 请按照以下步骤进行分析 1. 使用 web_search 工具搜索关键词: {query} 2. 阅读搜索结果提取关键信息 3. 对搜索结果进行综合分析 4. 给出结论和建议 4.7 测试与调试使用MCP Inspector图形化调试npx modelcontextprotocol/inspector在Inspector中加载Serverstdio模式命令python server.py即可交互测试所有Tool、Resource和Prompt。五、集成到Claude Code和Cursor5.1 Claude Code配置创建claude.json{ mcpServers: { my-assistant: { command: python, args: [path/to/server.py], env: { PYTHONUNBUFFERED: 1 } } } }启动Claude Code后自动发现Server的所有工具在对话中自然触发调用。5.2 Cursor配置创建.cursor/mcp.json{ mcpServers: { my-assistant: { command: python, args: [path/to/server.py], env: { PYTHONUNBUFFERED: 1 } } } }在Cursor的Settings → Features → MCP中查看已配置的Server和工具列表。5.3 多Server组合{ mcpServers: { my-filesystem: { command: python, args: [fs-server.py] }, my-search: { command: python, args: [search-server.py] }, my-database: { command: python, args: [db-server.py] } } }同一个对话中AI Agent可组合调用多个Server的能力——这就是MCP的即插即用体验。六、MCP vs 插件 vs A2A6.1 MCP vs 传统插件维度MCP传统插件协议开放标准私有格式厂商锁定能力发现动态协商自动暴露静态注册需预配置通信模式双向Server可推送单向Client调用多语言Python/TS/Java/Kotlin通常单语言6.2 MCP vs Google A2A互补而非竞争MCP解决Agent如何用工具A2A解决Agent之间如何通信。Anthropic与Google已宣布MCP A2A合作形成完整Agent生态栈。6.3 生态展望CNCF沙箱项目2026-03进入云原生基金会Streamable HTTPv1.2支持长时间运行任务Roots权限声明Server声明资源访问范围增强安全工具市场类似VS Code扩展市场MCP Server Marketplace正在形成七、总结30分钟你从零搭建了一个完整的MCP Server它能读文件、写文件、列目录能搜索网页获取实时信息能暴露系统状态资源能提供标准化的操作模板能即插即用地集成到Claude Code和Cursor下一步可以做什么添加数据库查询能力SQLite/PostgreSQL实现文件监听Watchdog Notification推送以SSE模式部署为远程服务参与MCP社区贡献Server参考资料MCP官方规范一级MCP Python SDK一级MCP官方示例仓库一级Anthropic MCP总览博客二级Claude Code MCP集成文档二级Cursor MCP集成文档二级