MCPModel Context Protocol是 Anthropic 提出的开放协议旨在让大模型如 Claude、ChatGPT以标准化方式调用外部工具和数据。它解决了传统 Agent 开发中“重复造轮子”和“接口不统一”的痛点。下面是一份从零开始的 MCP 开发实战指南。一、核心概念与开发定位在动手前先理清两个核心角色MCP Server服务端你主要开发的对象。它负责提供具体的工具Tools和数据Resources例如查询数据库、调用 API、读取文件。MCP Client客户端运行模型的环境。如 Claude Desktop、Cursor IDE、VS Code Copilot。它负责发现并调用你编写的 Server。开发流程的本质你编写一个独立的程序Server按照 MCP 协议基于 JSON-RPC与 AI 应用通信。写好后只需在客户端配置一次即可在所有支持 MCP 的平台上复用。二、Python 环境搭建与项目初始化Python 是目前 MCP 生态最成熟的语言推荐使用uv作为包管理器以提升依赖解析速度。# 1. 安装 uv (替代 pip)pipinstalluv# 2. 创建项目目录并初始化mkdirmy-mcp-servercdmy-mcp-server uv init# 3. 安装官方 SDK (推荐使用 FastMCP 简化开发)uvaddmcp[cli]uvaddfastmcp# 高级封装类似 FastAPI 的装饰器写法三、开发实战编写你的第一个 MCP Server我们将创建一个具备“数据库查询”和“文件读取”能力的 Server。1. 基础骨架server.pyfromfastmcpimportFastMCPimportos# 创建 Server 实例名称会显示在客户端mcpFastMCP(Internal-Data-Tools)2. 添加工具Tools查询数据库假设你有一个 PostgreSQL 数据库存储了项目信息。使用mcp.tool()装饰器将函数暴露给 AI。fromsqlalchemyimportcreate_engine,text# 模拟数据库连接实际使用环境变量DB_CONNECTION_STRINGpostgresqlpsycopg2://user:passlocalhost:5432/mydbenginecreate_engine(DB_CONNECTION_STRING)mcp.tool()defquery_project_status(project_id:int)-str:查询指定 ID 的项目研发状态。 Args: project_id: 项目的唯一标识 ID Returns: 包含项目状态的字符串描述 try:withengine.connect()asconn:# 使用参数化查询防止 SQL 注入sqltext(SELECT name, status, leader FROM projects WHERE id :pid)resultconn.execute(sql,{pid:project_id}).fetchone()ifresult:returnf项目名称:{result[0]}, 状态:{result[1]}, 负责人:{result[2]}returnf未找到 ID 为{project_id}的项目exceptExceptionase:returnf数据库查询出错:{str(e)}3. 添加资源Resources读取文档Resources 允许 AI 直接“读取”文件内容常用于 RAG 场景。importpypdf# 定义资源 URI 模式mcp.resource(docs://project-plan/{file_name})defread_project_plan(file_name:str)-str:读取项目计划 PDF 文件的内容。 资源 URI 格式: docs://project-plan/{file_name} file_pathos.path.join(data,f{file_name}.pdf)ifnotos.path.exists(file_path):return错误: 文件不存在try:text_contentwithopen(file_path,rb)asf:readerpypdf.PdfReader(f)forpageinreader.pages:text_contentpage.extract_text()returntext_contentexceptExceptionase:returnf读取 PDF 失败:{str(e)}4. 启动服务if__name____main__:# 开发模式使用 stdio标准输入输出与 Claude Desktop 通信mcp.run(transportstdio)# 生产模式如需远程调用使用 SSE# mcp.run(transportsse, port8000, host0.0.0.0)四、本地测试与调试1. 使用 MCP Inspector 调试Anthropic 提供了命令行调试工具无需启动完整客户端即可测试工具。# 安装 inspectoruvaddmcp[cli]# 运行调试确保在项目目录uv run mcp dev server.py2. 接入 Claude Desktop最常用Claude Desktop 是个人开发者的首选测试环境。找到配置文件macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json编辑配置在mcpServers字段中添加你的 Server。{mcpServers:{My Data Server:{command:python,args:[/absolute/path/to/your/server.py]}}}重启 Claude Desktop在输入框旁点击工具图标即可看到query_project_status工具。3. 接入 Cursor IDECursor 也原生支持 MCP配置方式类似。在项目根目录创建.cursor/mcp.json文件{mcpServers:{My Data Server:{command:python,args:[/absolute/path/to/server.py]}}}五、进阶生产环境部署与最佳实践1. 传输协议选择SSE over StdioStdio适合本地开发进程间直接通信。SSE (Server-Sent Events)推荐用于生产。将 Server 部署为 HTTP 服务支持远程调用和负载均衡。# 使用 SSE 模式启动需安装 uvicornif__name____main__:mcp.run(transportsse,port8000,host0.0.0.0)2. 安全与配置管理敏感信息绝对不要将 API Key、数据库密码硬编码在代码中。使用环境变量或.env文件。工具描述Description这是最重要的部分。AI 完全依赖函数的 Docstring 和参数类型提示来决定是否调用。描述必须清晰、包含示例否则 AI 无法正确使用你的工具 。3. 错误处理与日志MCP 协议要求 Server 必须稳定。务必在工具函数内部捕获所有异常并返回明确的错误信息给模型而不是让进程崩溃。六、常见问题FAQAI 不调用我的工具原因 1Docstring 描述不清晰。AI 无法理解工具用途。原因 2参数类型不匹配。确保使用str,int等标准类型。原因 3配置文件路径错误。Claude Desktop 需要绝对路径。支持哪些语言官方主力支持Python和TypeScript。社区有 Java、.NET 等 SDK但生态稍弱 。如何打包分发可以使用mcpb工具将 Server 打包为.mcpb文件方便团队一键安装 。MCP 的核心价值在于**“一次开发处处可用”**。你编写的这个 Server可以同时在 Claude、Cursor、VS Code 中工作极大提升了 AI 应用开发的效率。