最近在尝试将AI助手深度集成到开发工作流中时很多开发者都遇到了一个共同的瓶颈如何让AI模型安全、可控地访问和操作本地或远程的工具、数据库和API传统的提示词工程和函数调用Function Calling虽然有效但往往需要编写大量胶水代码且难以管理复杂的工具生态。如果你也为此困扰那么Claude最新推出的MCPModel Context Protocol协议及其生态的爆发式增长或许就是那个期待已久的答案。本文将从零开始为你系统拆解MCP的核心概念、工作原理并手把手教你如何基于Claude Code搭建自己的MCP服务端实现AI与外部世界的无缝连接。1. MCP协议重新定义AI与工具的交互方式在深入实践之前我们必须先理解MCP协议究竟是什么以及它为何能引发如此大的关注。1.1 MCP是什么解决什么问题MCP全称Model Context Protocol模型上下文协议是由Anthropic公司提出并开源的一种标准化协议。它的核心目标是为大型语言模型LLM提供一个统一、安全、可扩展的方式来发现、描述和调用外部工具与数据源。在没有MCP之前开发者通常面临以下困境工具集成碎片化每个AI应用如ChatGPT插件、Claude自定义工具都需要单独适配和对接工作重复且低效。权限控制复杂很难精细控制AI模型能访问哪些工具和数据存在安全风险。开发体验割裂工具的开发、描述、调用流程不统一学习成本高。MCP协议通过定义一套清晰的客户端-服务器架构和通信规范完美解决了这些问题。它将AI模型客户端与工具提供方服务器解耦使得工具开发者可以专注于实现功能而AI应用开发者则可以轻松集成海量工具。1.2 MCP的核心架构与核心概念MCP的架构非常清晰主要包含三个角色MCP 客户端 (Client)通常是AI应用本身如Claude Desktop、Claude Code、Cursor等。它负责发起请求调用服务器提供的工具。MCP 服务器 (Server)工具或数据的提供方。它向客户端宣告自己提供了哪些“资源”Resources如文件、数据库连接和“工具”Tools即可执行函数。MCP 传输层 (Transport)定义客户端与服务器之间的通信方式。目前主要支持两种stdio标准输入输出适用于本地进程间通信简单高效。SSEServer-Sent Events适用于远程HTTP通信支持跨网络调用。整个交互流程可以简化为客户端启动时连接到配置好的MCP服务器服务器告知客户端自己有哪些资源和工具当用户需要时客户端请求服务器执行特定工具或读取资源服务器执行并返回结果。2. 环境准备搭建你的MCP开发与实验环境理解了理论我们开始动手。要体验和开发MCP你需要准备以下环境。2.1 安装Claude CodeMCP客户端Claude Code是Anthropic官方推出的代码编辑器内置了对MCP协议的原生支持是我们进行MCP开发和测试的最佳客户端。安装步骤访问官网前往Claude Code的官方网站通常为claude.ai/code根据你的操作系统Windows/macOS/Linux下载对应的安装包。安装与登录运行安装程序完成安装后打开Claude Code。你需要使用Claude账号登录。如果遇到“暂时无法为新用户提供服务”的提示可能需要等待或使用已有账号。验证安装打开Claude Code你应该能看到一个类似VS Code的界面侧边栏有Claude的聊天面板。2.2 配置开发环境Python/Node.jsMCP服务器可以使用任何语言编写只要遵循协议规范即可。官方提供了Python和TypeScript/Node.js的SDK极大降低了开发门槛。这里我们以Python环境为例。Python环境配置# 1. 确保已安装Python推荐3.9以上版本 python --version # 2. 创建一个干净的虚拟环境可选但推荐 python -m venv mcp-venv # 3. 激活虚拟环境 # Windows: mcp-venv\Scripts\activate # macOS/Linux: source mcp-venv/bin/activate # 4. 安装官方MCP SDK pip install mcpNode.js环境配置备选# 1. 确保已安装Node.js推荐18以上版本和npm node --version npm --version # 2. 初始化一个新项目可选 mkdir my-mcp-server cd my-mcp-server npm init -y # 3. 安装官方MCP SDK npm install modelcontextprotocol/sdk3. 开发你的第一个MCP服务器一个简单的计算器现在让我们用Python SDK开发一个最简单的MCP服务器它提供一个计算器工具。3.1 项目结构与核心代码创建一个名为simple_calculator_server.py的文件。# simple_calculator_server.py import asyncio from mcp.server import Server from mcp.server.models import InitializationOptions import mcp.server.stdio from mcp.types import Tool, TextContent # 1. 创建MCP服务器实例 server Server(simple-calculator) # 2. 定义工具Tools # 这里我们定义一个加法计算工具 server.list_tools() async def handle_list_tools(): return [ Tool( nameadd_numbers, descriptionAdd two numbers together., inputSchema{ type: object, properties: { a: {type: number, description: The first number}, b: {type: number, description: The second number}, }, required: [a, b], }, ) ] # 3. 实现工具的执行逻辑 server.call_tool() async def handle_call_tool(name: str, arguments: dict): if name add_numbers: a arguments.get(a) b arguments.get(b) if isinstance(a, (int, float)) and isinstance(b, (int, float)): result a b # 返回结果必须遵循特定的Content格式 return [TextContent(typetext, textfThe sum of {a} and {b} is {result}.)] else: raise ValueError(Both a and b must be numbers.) else: raise ValueError(fUnknown tool: {name}) # 4. 主函数启动服务器使用stdio传输 async def main(): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream, InitializationOptions()) if __name__ __main__: asyncio.run(main())代码解读创建服务器Server(“simple-calculator”)初始化一个MCP服务器并给它一个名字。声明工具server.list_tools()装饰器下的函数用于向客户端宣告本服务器提供了哪些工具。我们定义了一个名为add_numbers的工具并描述了它的输入参数模式Schema。执行工具server.call_tool()装饰器下的函数是工具被调用时的实际处理逻辑。我们根据工具名name和传入的参数arguments执行加法运算并将结果封装成TextContent返回。启动服务main()函数使用stdio传输层启动服务器等待客户端连接。3.2 在Claude Code中配置并连接MCP服务器要让Claude Code使用我们这个服务器需要进行配置。找到Claude Code配置目录macOS/Linux:~/.config/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json编辑配置文件如果文件不存在就创建它。添加以下内容将command路径替换为你Python解释器和脚本的实际路径。{ mcpServers: { simple-calculator: { command: /path/to/your/mcp-venv/bin/python, args: [/path/to/your/simple_calculator_server.py] } } }Windows示例:{ mcpServers: { simple-calculator: { command: C:\\Users\\YourName\\mcp-venv\\Scripts\\python.exe, args: [C:\\Projects\\mcp\\simple_calculator_server.py] } } }重启Claude Code保存配置文件后完全关闭并重新打开Claude Code。验证连接在Claude Code的聊天框中你可以尝试输入“请使用计算器工具计算一下123加456。” Claude应该能识别出你配置的add_numbers工具并询问你参数或直接给出结果。你也可以在输入框下方的“工具”按钮中看到已可用的工具列表。4. 开发进阶MCP服务器连接SQLite数据库一个简单的计算器展示了基础流程。接下来我们开发一个更实用的服务器连接SQLite数据库让Claude可以查询数据。4.1 项目结构与依赖创建一个新目录例如sqlite-mcp-server。mkdir sqlite-mcp-server cd sqlite-mcp-server python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install mcp准备一个示例SQLite数据库文件example.db你可以用以下Python脚本快速创建并插入一些数据# create_sample_db.py import sqlite3 conn sqlite3.connect(example.db) cursor conn.cursor() cursor.execute(CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)) cursor.execute(INSERT INTO users (name, email) VALUES (Alice, aliceexample.com)) cursor.execute(INSERT INTO users (name, email) VALUES (Bob, bobexample.com)) conn.commit() conn.close() print(Sample database created.)4.2 编写SQLite MCP服务器创建sqlite_server.py文件。# sqlite_server.py import asyncio import sqlite3 import json from pathlib import Path from typing import Any from mcp.server import Server from mcp.server.models import InitializationOptions import mcp.server.stdio from mcp.types import Tool, TextContent, ImageContent server Server(sqlite-query-server) # 数据库文件路径可以设计成通过配置传入 DB_PATH Path(__file__).parent / example.db server.list_tools() async def handle_list_tools(): return [ Tool( namequery_sqlite, descriptionExecute a read-only SQL SELECT query on the example SQLite database. Use this to get data., inputSchema{ type: object, properties: { sql: { type: string, description: The SQL SELECT query to execute. ONLY USE READ-ONLY QUERIES. Example: SELECT * FROM users LIMIT 5 } }, required: [sql], }, ), Tool( namelist_tables, descriptionList all tables in the connected SQLite database., inputSchema{type: object, properties: {}}, # 此工具不需要参数 ) ] server.call_tool() async def handle_call_tool(name: str, arguments: dict): if name list_tables: return await _handle_list_tables() elif name query_sqlite: sql arguments.get(sql, ) if not sql.strip().upper().startswith(SELECT): return [TextContent(typetext, textError: For safety, only SELECT queries are allowed.)] return await _handle_query(sql) else: raise ValueError(fUnknown tool: {name}) async def _handle_list_tables(): 内部函数列出所有表 try: conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute(SELECT name FROM sqlite_master WHERE typetable;) tables cursor.fetchall() conn.close() table_list \n.join([f- {table[0]} for table in tables]) return [TextContent(typetext, textfTables in database:\n{table_list})] except Exception as e: return [TextContent(typetext, textfError listing tables: {e})] async def _handle_query(sql: str): 内部函数执行查询 try: conn sqlite3.connect(DB_PATH) conn.row_factory sqlite3.Row # 以字典形式返回行 cursor conn.cursor() cursor.execute(sql) rows cursor.fetchall() conn.close() if not rows: return [TextContent(typetext, textQuery executed successfully. No rows returned.)] # 将结果格式化为易读的表格文本 headers rows[0].keys() # 简单格式化 result_text | .join(headers) \n - * (len(headers)*10) \n for row in rows: result_text | .join(str(row[h]) for h in headers) \n return [TextContent(typetext, textfQuery Results:\n\n{result_text}\n)] except sqlite3.Error as e: return [TextContent(typetext, textfSQLite Error: {e})] except Exception as e: return [TextContent(typetext, textfUnexpected error: {e}) async def main(): print(fSQLite MCP Server starting, using database at: {DB_PATH}, filesys.stderr) async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream, InitializationOptions()) if __name__ __main__: asyncio.run(main())4.3 配置与使用配置Claude Code像之前一样修改claude_desktop_config.json添加这个新的服务器配置。{ mcpServers: { simple-calculator: { ... }, sqlite-server: { command: /path/to/sqlite-mcp-server/venv/bin/python, args: [/path/to/sqlite-mcp-server/sqlite_server.py] } } }重启并测试重启Claude Code后你可以直接对Claude说“帮我看看数据库里有哪些表” Claude会调用list_tables工具。然后你可以说“查询一下users表里的所有数据。” Claude会调用query_sqlite工具并返回格式化的结果。安全提示在生产环境中务必严格限制工具权限。如上例所示我们只在工具描述和代码逻辑中允许SELECT查询防止数据被意外修改或删除。更完善的方案应包括连接池、查询超时、SQL注入过滤等。5. 探索丰富的MCP生态与现成服务器除了自己开发MCP生态已经涌现出大量优秀的开源服务器可以直接集成使用极大扩展Claude的能力。5.1 如何集成社区MCP服务器社区服务器通常以NPM包或Docker镜像的形式提供。以modelcontextprotocol/server-sqlite这个官方示例服务器为例集成步骤如下通过NPM安装假设你已安装Node.jsnpm install -g modelcontextprotocol/server-sqlite这会全局安装一个可执行文件mcp-server-sqlite。配置Claude Code修改配置文件通过command直接调用这个可执行文件并通过args传递参数如数据库路径。{ mcpServers: { community-sqlite: { command: mcp-server-sqlite, args: [/path/to/your/database.db] } } }5.2 热门MCP服务器推荐根据网络热度以下方向的MCP服务器非常活跃值得关注和尝试开发与调试工具chrome-devtools-mcp: 连接Chrome DevTools让AI可以调试网页、分析性能。playwright-mcp: 集成Playwright浏览器自动化框架可用于网页抓取、测试等。代码与逆向工程jadx-mcp: 集成JADX用于分析Android APK文件。ida-mcp: 集成IDA Pro辅助二进制代码分析与逆向工程需本地安装IDA。设计与数据科学蓝湖MCP 连接蓝湖设计平台获取设计稿信息需关注具体实现。matlab-mcp: 连接MATLAB进行科学计算和数据分析。stata-mcp: 连接Stata统计软件。系统与硬件esp-idf-mcp: 用于ESP32物联网开发框架。通达信MCP 连接通达信金融终端需关注具体实现。通用工具filesystem 访问文件系统需谨慎配置权限。curl 执行HTTP请求。postgres/mysql: 连接各类数据库。集成建议在集成任何第三方服务器前务必审查其代码或来源确保其安全性避免执行恶意命令或泄露敏感数据。6. 常见问题与深度排错指南在配置和使用MCP过程中你可能会遇到以下问题。6.1 配置与连接问题问题现象可能原因排查步骤与解决方案Claude Code重启后看不到新工具1. 配置文件路径错误。2. 配置文件格式错误JSON语法。3. MCP服务器启动失败。1. 检查配置文件路径是否正确尤其是Windows的路径分隔符和转义。2. 使用JSON验证工具如 jsonlint.com 检查配置文件。3. 在终端手动运行配置中的command和args看服务器能否正常启动并输出日志。错误提示“Failed to start server ‘xxx’”1. 命令路径不存在或无执行权限。2. 依赖未安装如Python包。3. 服务器脚本本身有语法错误。1. 确保command指向的Python/Node可执行文件路径绝对正确。2. 在服务器所在目录的虚拟环境中检查pip list | grep mcp或npm list确认依赖已安装。3. 手动运行服务器脚本查看具体的Python/Node报错信息。工具调用后无反应或超时1. 服务器处理逻辑卡死如死循环。2. 网络请求慢SSE传输。3. 工具返回格式不符合MCP协议。1. 在服务器代码中添加日志观察执行流程。2. 对于本地服务器优先使用stdio传输。3. 确保server.call_tool处理函数返回的是List[Content]对象如[TextContent(...)]。6.2 Claude Code 特定问题“Claude is not available to new users right now”这是Claude平台自身的注册限制与MCP功能无关。需要等待开放或使用已有权限的账号。“deepseek-v4-pro is not a model this version of claude code recognizes”Claude Code主要设计用于连接Claude系列模型。此错误提示你可能在配置中错误地指定了其他不支持的模型名称检查相关模型配置。找不到“工具”按钮或面板确保Claude Code版本较新并支持MCP。工具列表通常出现在输入框下方或侧边栏。如果配置了服务器但未显示参考上表的连接问题排查。6.3 MCP服务器开发问题协议版本不兼容MCP协议仍在发展中。确保你使用的mcpSDK版本与Claude Code客户端大致兼容。关注Anthropic官方公告。工具描述Schema不规范inputSchema必须遵循JSON Schema规范。描述不清会导致Claude无法正确理解和使用工具。使用在线JSON Schema验证器进行检查。资源Resources与工具Tools混淆Resources通常用于声明只读的数据源如文件内容、API文档Tools用于声明可执行的操作。根据你的场景正确选择。7. 最佳实践与工程化建议要将MCP用于实际项目遵循以下最佳实践至关重要。7.1 安全性是第一要务最小权限原则MCP服务器应只拥有完成其功能所必需的最小权限。例如一个文件搜索服务器不需要删除文件的权限。输入验证与过滤对所有来自客户端的输入如SQL语句、文件路径、命令参数进行严格的验证、转义和过滤防止注入攻击。沙箱环境考虑在Docker容器或安全沙箱中运行不受完全信任的MCP服务器以隔离潜在风险。审计日志记录所有工具调用的请求和响应注意避免记录敏感数据便于事后审计和问题排查。网络隔离对于SSE传输的远程服务器使用防火墙规则、VPC、认证令牌等手段控制访问。7.2 设计与开发规范清晰的工具命名与描述工具名应使用动词开头如query_database,convert_image。描述应清晰说明功能、输入参数和副作用。健壮的错误处理在服务器代码中全面捕获异常并返回对用户友好的错误信息而不是内部堆栈跟踪。资源管理妥善管理数据库连接、文件句柄、网络连接等资源使用with语句或try-finally确保其被正确关闭。版本化与兼容性如果你的服务器对外提供考虑进行版本管理。在工具描述或服务器初始化信息中声明版本号避免破坏性变更影响现有客户端。提供使用示例在工具描述或单独的文档中给出清晰的调用示例帮助LLM客户端更好地理解如何使用你的工具。7.3 性能与可维护性异步编程MCP SDK基于异步I/Oasyncio。确保你的工具处理逻辑也是异步的避免阻塞事件循环尤其是在执行I/O密集型操作时。超时机制为长时间运行的工具设置超时防止客户端长时间等待。配置化将数据库连接字符串、API密钥、文件路径等配置信息外部化通过环境变量或配置文件而不是硬编码在脚本中。单元测试为你的工具逻辑编写单元测试确保核心功能的正确性。MCP协议的兴起标志着AI从“对话式助手”向“可执行智能体”演进的关键一步。它通过标准化接口将AI模型与无限的外部能力连接起来释放了巨大的生产力潜力。通过本文你已经掌握了MCP的核心概念、学会了如何从零开发一个MCP服务器并了解了如何集成丰富的社区生态。下一步你可以尝试将MCP应用于你的具体场景比如连接内部API、操作云资源、分析日志文件或者为你常用的开发工具打造一个智能助手。记住从简单的工具开始逐步迭代并始终将安全设计放在首位。 
长河君 · 2026/8/14 21:13:05 · 阅读 1.2k 从零构建MCP服务器：实现AI与外部工具的安全可控连接
最近在尝试将AI助手深度集成到开发工作流中时很多开发者都遇到了一个共同的瓶颈如何让AI模型安全、可控地访问和操作本地或远程的工具、数据库和API传统的提示词工程和函数调用Function Calling虽然有效但往往需要编写大量胶水代码且难以管理复杂的工具生态。如果你也为此困扰那么Claude最新推出的MCPModel Context Protocol协议及其生态的爆发式增长或许就是那个期待已久的答案。本文将从零开始为你系统拆解MCP的核心概念、工作原理并手把手教你如何基于Claude Code搭建自己的MCP服务端实现AI与外部世界的无缝连接。1. MCP协议重新定义AI与工具的交互方式在深入实践之前我们必须先理解MCP协议究竟是什么以及它为何能引发如此大的关注。1.1 MCP是什么解决什么问题MCP全称Model Context Protocol模型上下文协议是由Anthropic公司提出并开源的一种标准化协议。它的核心目标是为大型语言模型LLM提供一个统一、安全、可扩展的方式来发现、描述和调用外部工具与数据源。在没有MCP之前开发者通常面临以下困境工具集成碎片化每个AI应用如ChatGPT插件、Claude自定义工具都需要单独适配和对接工作重复且低效。权限控制复杂很难精细控制AI模型能访问哪些工具和数据存在安全风险。开发体验割裂工具的开发、描述、调用流程不统一学习成本高。MCP协议通过定义一套清晰的客户端-服务器架构和通信规范完美解决了这些问题。它将AI模型客户端与工具提供方服务器解耦使得工具开发者可以专注于实现功能而AI应用开发者则可以轻松集成海量工具。1.2 MCP的核心架构与核心概念MCP的架构非常清晰主要包含三个角色MCP 客户端 (Client)通常是AI应用本身如Claude Desktop、Claude Code、Cursor等。它负责发起请求调用服务器提供的工具。MCP 服务器 (Server)工具或数据的提供方。它向客户端宣告自己提供了哪些“资源”Resources如文件、数据库连接和“工具”Tools即可执行函数。MCP 传输层 (Transport)定义客户端与服务器之间的通信方式。目前主要支持两种stdio标准输入输出适用于本地进程间通信简单高效。SSEServer-Sent Events适用于远程HTTP通信支持跨网络调用。整个交互流程可以简化为客户端启动时连接到配置好的MCP服务器服务器告知客户端自己有哪些资源和工具当用户需要时客户端请求服务器执行特定工具或读取资源服务器执行并返回结果。2. 环境准备搭建你的MCP开发与实验环境理解了理论我们开始动手。要体验和开发MCP你需要准备以下环境。2.1 安装Claude CodeMCP客户端Claude Code是Anthropic官方推出的代码编辑器内置了对MCP协议的原生支持是我们进行MCP开发和测试的最佳客户端。安装步骤访问官网前往Claude Code的官方网站通常为claude.ai/code根据你的操作系统Windows/macOS/Linux下载对应的安装包。安装与登录运行安装程序完成安装后打开Claude Code。你需要使用Claude账号登录。如果遇到“暂时无法为新用户提供服务”的提示可能需要等待或使用已有账号。验证安装打开Claude Code你应该能看到一个类似VS Code的界面侧边栏有Claude的聊天面板。2.2 配置开发环境Python/Node.jsMCP服务器可以使用任何语言编写只要遵循协议规范即可。官方提供了Python和TypeScript/Node.js的SDK极大降低了开发门槛。这里我们以Python环境为例。Python环境配置# 1. 确保已安装Python推荐3.9以上版本 python --version # 2. 创建一个干净的虚拟环境可选但推荐 python -m venv mcp-venv # 3. 激活虚拟环境 # Windows: mcp-venv\Scripts\activate # macOS/Linux: source mcp-venv/bin/activate # 4. 安装官方MCP SDK pip install mcpNode.js环境配置备选# 1. 确保已安装Node.js推荐18以上版本和npm node --version npm --version # 2. 初始化一个新项目可选 mkdir my-mcp-server cd my-mcp-server npm init -y # 3. 安装官方MCP SDK npm install modelcontextprotocol/sdk3. 开发你的第一个MCP服务器一个简单的计算器现在让我们用Python SDK开发一个最简单的MCP服务器它提供一个计算器工具。3.1 项目结构与核心代码创建一个名为simple_calculator_server.py的文件。# simple_calculator_server.py import asyncio from mcp.server import Server from mcp.server.models import InitializationOptions import mcp.server.stdio from mcp.types import Tool, TextContent # 1. 创建MCP服务器实例 server Server(simple-calculator) # 2. 定义工具Tools # 这里我们定义一个加法计算工具 server.list_tools() async def handle_list_tools(): return [ Tool( nameadd_numbers, descriptionAdd two numbers together., inputSchema{ type: object, properties: { a: {type: number, description: The first number}, b: {type: number, description: The second number}, }, required: [a, b], }, ) ] # 3. 实现工具的执行逻辑 server.call_tool() async def handle_call_tool(name: str, arguments: dict): if name add_numbers: a arguments.get(a) b arguments.get(b) if isinstance(a, (int, float)) and isinstance(b, (int, float)): result a b # 返回结果必须遵循特定的Content格式 return [TextContent(typetext, textfThe sum of {a} and {b} is {result}.)] else: raise ValueError(Both a and b must be numbers.) else: raise ValueError(fUnknown tool: {name}) # 4. 主函数启动服务器使用stdio传输 async def main(): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream, InitializationOptions()) if __name__ __main__: asyncio.run(main())代码解读创建服务器Server(“simple-calculator”)初始化一个MCP服务器并给它一个名字。声明工具server.list_tools()装饰器下的函数用于向客户端宣告本服务器提供了哪些工具。我们定义了一个名为add_numbers的工具并描述了它的输入参数模式Schema。执行工具server.call_tool()装饰器下的函数是工具被调用时的实际处理逻辑。我们根据工具名name和传入的参数arguments执行加法运算并将结果封装成TextContent返回。启动服务main()函数使用stdio传输层启动服务器等待客户端连接。3.2 在Claude Code中配置并连接MCP服务器要让Claude Code使用我们这个服务器需要进行配置。找到Claude Code配置目录macOS/Linux:~/.config/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json编辑配置文件如果文件不存在就创建它。添加以下内容将command路径替换为你Python解释器和脚本的实际路径。{ mcpServers: { simple-calculator: { command: /path/to/your/mcp-venv/bin/python, args: [/path/to/your/simple_calculator_server.py] } } }Windows示例:{ mcpServers: { simple-calculator: { command: C:\\Users\\YourName\\mcp-venv\\Scripts\\python.exe, args: [C:\\Projects\\mcp\\simple_calculator_server.py] } } }重启Claude Code保存配置文件后完全关闭并重新打开Claude Code。验证连接在Claude Code的聊天框中你可以尝试输入“请使用计算器工具计算一下123加456。” Claude应该能识别出你配置的add_numbers工具并询问你参数或直接给出结果。你也可以在输入框下方的“工具”按钮中看到已可用的工具列表。4. 开发进阶MCP服务器连接SQLite数据库一个简单的计算器展示了基础流程。接下来我们开发一个更实用的服务器连接SQLite数据库让Claude可以查询数据。4.1 项目结构与依赖创建一个新目录例如sqlite-mcp-server。mkdir sqlite-mcp-server cd sqlite-mcp-server python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install mcp准备一个示例SQLite数据库文件example.db你可以用以下Python脚本快速创建并插入一些数据# create_sample_db.py import sqlite3 conn sqlite3.connect(example.db) cursor conn.cursor() cursor.execute(CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)) cursor.execute(INSERT INTO users (name, email) VALUES (Alice, aliceexample.com)) cursor.execute(INSERT INTO users (name, email) VALUES (Bob, bobexample.com)) conn.commit() conn.close() print(Sample database created.)4.2 编写SQLite MCP服务器创建sqlite_server.py文件。# sqlite_server.py import asyncio import sqlite3 import json from pathlib import Path from typing import Any from mcp.server import Server from mcp.server.models import InitializationOptions import mcp.server.stdio from mcp.types import Tool, TextContent, ImageContent server Server(sqlite-query-server) # 数据库文件路径可以设计成通过配置传入 DB_PATH Path(__file__).parent / example.db server.list_tools() async def handle_list_tools(): return [ Tool( namequery_sqlite, descriptionExecute a read-only SQL SELECT query on the example SQLite database. Use this to get data., inputSchema{ type: object, properties: { sql: { type: string, description: The SQL SELECT query to execute. ONLY USE READ-ONLY QUERIES. Example: SELECT * FROM users LIMIT 5 } }, required: [sql], }, ), Tool( namelist_tables, descriptionList all tables in the connected SQLite database., inputSchema{type: object, properties: {}}, # 此工具不需要参数 ) ] server.call_tool() async def handle_call_tool(name: str, arguments: dict): if name list_tables: return await _handle_list_tables() elif name query_sqlite: sql arguments.get(sql, ) if not sql.strip().upper().startswith(SELECT): return [TextContent(typetext, textError: For safety, only SELECT queries are allowed.)] return await _handle_query(sql) else: raise ValueError(fUnknown tool: {name}) async def _handle_list_tables(): 内部函数列出所有表 try: conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute(SELECT name FROM sqlite_master WHERE typetable;) tables cursor.fetchall() conn.close() table_list \n.join([f- {table[0]} for table in tables]) return [TextContent(typetext, textfTables in database:\n{table_list})] except Exception as e: return [TextContent(typetext, textfError listing tables: {e})] async def _handle_query(sql: str): 内部函数执行查询 try: conn sqlite3.connect(DB_PATH) conn.row_factory sqlite3.Row # 以字典形式返回行 cursor conn.cursor() cursor.execute(sql) rows cursor.fetchall() conn.close() if not rows: return [TextContent(typetext, textQuery executed successfully. No rows returned.)] # 将结果格式化为易读的表格文本 headers rows[0].keys() # 简单格式化 result_text | .join(headers) \n - * (len(headers)*10) \n for row in rows: result_text | .join(str(row[h]) for h in headers) \n return [TextContent(typetext, textfQuery Results:\n\n{result_text}\n)] except sqlite3.Error as e: return [TextContent(typetext, textfSQLite Error: {e})] except Exception as e: return [TextContent(typetext, textfUnexpected error: {e}) async def main(): print(fSQLite MCP Server starting, using database at: {DB_PATH}, filesys.stderr) async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream, InitializationOptions()) if __name__ __main__: asyncio.run(main())4.3 配置与使用配置Claude Code像之前一样修改claude_desktop_config.json添加这个新的服务器配置。{ mcpServers: { simple-calculator: { ... }, sqlite-server: { command: /path/to/sqlite-mcp-server/venv/bin/python, args: [/path/to/sqlite-mcp-server/sqlite_server.py] } } }重启并测试重启Claude Code后你可以直接对Claude说“帮我看看数据库里有哪些表” Claude会调用list_tables工具。然后你可以说“查询一下users表里的所有数据。” Claude会调用query_sqlite工具并返回格式化的结果。安全提示在生产环境中务必严格限制工具权限。如上例所示我们只在工具描述和代码逻辑中允许SELECT查询防止数据被意外修改或删除。更完善的方案应包括连接池、查询超时、SQL注入过滤等。5. 探索丰富的MCP生态与现成服务器除了自己开发MCP生态已经涌现出大量优秀的开源服务器可以直接集成使用极大扩展Claude的能力。5.1 如何集成社区MCP服务器社区服务器通常以NPM包或Docker镜像的形式提供。以modelcontextprotocol/server-sqlite这个官方示例服务器为例集成步骤如下通过NPM安装假设你已安装Node.jsnpm install -g modelcontextprotocol/server-sqlite这会全局安装一个可执行文件mcp-server-sqlite。配置Claude Code修改配置文件通过command直接调用这个可执行文件并通过args传递参数如数据库路径。{ mcpServers: { community-sqlite: { command: mcp-server-sqlite, args: [/path/to/your/database.db] } } }5.2 热门MCP服务器推荐根据网络热度以下方向的MCP服务器非常活跃值得关注和尝试开发与调试工具chrome-devtools-mcp: 连接Chrome DevTools让AI可以调试网页、分析性能。playwright-mcp: 集成Playwright浏览器自动化框架可用于网页抓取、测试等。代码与逆向工程jadx-mcp: 集成JADX用于分析Android APK文件。ida-mcp: 集成IDA Pro辅助二进制代码分析与逆向工程需本地安装IDA。设计与数据科学蓝湖MCP 连接蓝湖设计平台获取设计稿信息需关注具体实现。matlab-mcp: 连接MATLAB进行科学计算和数据分析。stata-mcp: 连接Stata统计软件。系统与硬件esp-idf-mcp: 用于ESP32物联网开发框架。通达信MCP 连接通达信金融终端需关注具体实现。通用工具filesystem 访问文件系统需谨慎配置权限。curl 执行HTTP请求。postgres/mysql: 连接各类数据库。集成建议在集成任何第三方服务器前务必审查其代码或来源确保其安全性避免执行恶意命令或泄露敏感数据。6. 常见问题与深度排错指南在配置和使用MCP过程中你可能会遇到以下问题。6.1 配置与连接问题问题现象可能原因排查步骤与解决方案Claude Code重启后看不到新工具1. 配置文件路径错误。2. 配置文件格式错误JSON语法。3. MCP服务器启动失败。1. 检查配置文件路径是否正确尤其是Windows的路径分隔符和转义。2. 使用JSON验证工具如 jsonlint.com 检查配置文件。3. 在终端手动运行配置中的command和args看服务器能否正常启动并输出日志。错误提示“Failed to start server ‘xxx’”1. 命令路径不存在或无执行权限。2. 依赖未安装如Python包。3. 服务器脚本本身有语法错误。1. 确保command指向的Python/Node可执行文件路径绝对正确。2. 在服务器所在目录的虚拟环境中检查pip list | grep mcp或npm list确认依赖已安装。3. 手动运行服务器脚本查看具体的Python/Node报错信息。工具调用后无反应或超时1. 服务器处理逻辑卡死如死循环。2. 网络请求慢SSE传输。3. 工具返回格式不符合MCP协议。1. 在服务器代码中添加日志观察执行流程。2. 对于本地服务器优先使用stdio传输。3. 确保server.call_tool处理函数返回的是List[Content]对象如[TextContent(...)]。6.2 Claude Code 特定问题“Claude is not available to new users right now”这是Claude平台自身的注册限制与MCP功能无关。需要等待开放或使用已有权限的账号。“deepseek-v4-pro is not a model this version of claude code recognizes”Claude Code主要设计用于连接Claude系列模型。此错误提示你可能在配置中错误地指定了其他不支持的模型名称检查相关模型配置。找不到“工具”按钮或面板确保Claude Code版本较新并支持MCP。工具列表通常出现在输入框下方或侧边栏。如果配置了服务器但未显示参考上表的连接问题排查。6.3 MCP服务器开发问题协议版本不兼容MCP协议仍在发展中。确保你使用的mcpSDK版本与Claude Code客户端大致兼容。关注Anthropic官方公告。工具描述Schema不规范inputSchema必须遵循JSON Schema规范。描述不清会导致Claude无法正确理解和使用工具。使用在线JSON Schema验证器进行检查。资源Resources与工具Tools混淆Resources通常用于声明只读的数据源如文件内容、API文档Tools用于声明可执行的操作。根据你的场景正确选择。7. 最佳实践与工程化建议要将MCP用于实际项目遵循以下最佳实践至关重要。7.1 安全性是第一要务最小权限原则MCP服务器应只拥有完成其功能所必需的最小权限。例如一个文件搜索服务器不需要删除文件的权限。输入验证与过滤对所有来自客户端的输入如SQL语句、文件路径、命令参数进行严格的验证、转义和过滤防止注入攻击。沙箱环境考虑在Docker容器或安全沙箱中运行不受完全信任的MCP服务器以隔离潜在风险。审计日志记录所有工具调用的请求和响应注意避免记录敏感数据便于事后审计和问题排查。网络隔离对于SSE传输的远程服务器使用防火墙规则、VPC、认证令牌等手段控制访问。7.2 设计与开发规范清晰的工具命名与描述工具名应使用动词开头如query_database,convert_image。描述应清晰说明功能、输入参数和副作用。健壮的错误处理在服务器代码中全面捕获异常并返回对用户友好的错误信息而不是内部堆栈跟踪。资源管理妥善管理数据库连接、文件句柄、网络连接等资源使用with语句或try-finally确保其被正确关闭。版本化与兼容性如果你的服务器对外提供考虑进行版本管理。在工具描述或服务器初始化信息中声明版本号避免破坏性变更影响现有客户端。提供使用示例在工具描述或单独的文档中给出清晰的调用示例帮助LLM客户端更好地理解如何使用你的工具。7.3 性能与可维护性异步编程MCP SDK基于异步I/Oasyncio。确保你的工具处理逻辑也是异步的避免阻塞事件循环尤其是在执行I/O密集型操作时。超时机制为长时间运行的工具设置超时防止客户端长时间等待。配置化将数据库连接字符串、API密钥、文件路径等配置信息外部化通过环境变量或配置文件而不是硬编码在脚本中。单元测试为你的工具逻辑编写单元测试确保核心功能的正确性。MCP协议的兴起标志着AI从“对话式助手”向“可执行智能体”演进的关键一步。它通过标准化接口将AI模型与无限的外部能力连接起来释放了巨大的生产力潜力。通过本文你已经掌握了MCP的核心概念、学会了如何从零开发一个MCP服务器并了解了如何集成丰富的社区生态。下一步你可以尝试将MCP应用于你的具体场景比如连接内部API、操作云资源、分析日志文件或者为你常用的开发工具打造一个智能助手。记住从简单的工具开始逐步迭代并始终将安全设计放在首位。