在实际 AI 应用开发中我们经常需要让大语言模型LLM能够安全、可控地访问外部工具、数据或服务。无论是让 AI 查询数据库、调用 API还是操作本地文件都需要一个标准化的通信协议来桥接模型与外部系统。Model Context ProtocolMCP正是为解决这一问题而设计的开放协议它定义了 AI 应用客户端与外部资源服务器之间如何交换上下文信息和执行操作。对于开发者而言理解并配置 MCP 的本地开发环境是构建自定义 AI 能力、实现智能体Agent工具化扩展的第一步。本文将以“TARE”作为一个示例项目代号带你从零开始完成 MCP 服务器Server的本地环境配置、基础功能开发并最终实现与 Claude Desktop 或 Cursor 等客户端的连接测试。你将了解到 MCP 的核心概念、协议的工作流程并掌握使用 Python 编写一个简单 MCP 服务器的完整步骤。无论你是想为内部系统添加 AI 接口还是希望探索 AI 智能体与现有工作流的深度集成本文提供的实践路径都将为你打下坚实的基础。1. 理解 MCP 协议模型与外部世界的桥梁在深入配置之前必须先厘清 MCP 是什么以及它试图解决的核心问题。这有助于我们在后续开发中做出正确的设计决策。1.1 MCP 要解决什么问题大语言模型本身是一个封闭的“大脑”它拥有强大的推理和生成能力但缺乏感知和操作外部世界如数据库、文件系统、API的直接手段。传统的做法是通过在提示词Prompt中硬编码 API 调用说明或者让模型输出特定格式的指令再由后端解析执行。这种方式存在几个明显缺陷上下文污染冗长的工具描述会挤占宝贵的上下文窗口。格式脆弱模型输出的指令格式容易出错解析逻辑复杂。安全性差模型可能直接输出危险的系统命令。扩展性低每增加一个工具都需要修改提示词和后端代码。MCP 协议旨在标准化 AI 客户端如 Claude Desktop, Cursor与工具服务端之间的通信。它将工具Tools和资源Resources抽象为标准的接口客户端通过协议发现服务器提供了哪些能力并以结构化的方式调用它们。这样开发者可以独立开发功能强大的 MCP 服务器而 AI 应用只需实现一次协议对接就能动态接入所有兼容的服务器。1.2 MCP 核心概念与交互流程一次完整的 MCP 调用涉及以下几个核心部分MCP 客户端Client通常是集成了 MCP 协议的 AI 应用如 Claude Desktop、Cursor IDE、Windmill 等。它负责初始化连接、列出可用工具/资源并在用户需要时发起调用。MCP 服务器Server由开发者编写的程序它向客户端宣告自己提供的工具和资源。当客户端调用某个工具时服务器执行相应的业务逻辑如查询数据库、调用天气 API并返回结果。工具Tools服务器提供的可执行操作。每个工具都有名称、描述、输入参数定义。例如一个query_database工具参数是 SQL 语句。资源Resources服务器提供的可读数据源。每个资源有 URI、MIME 类型和内容。例如一个file:///etc/hosts资源内容是该文件的数据。客户端可以将资源内容作为上下文提供给模型。传输协议Transport客户端与服务器之间的通信方式。MCP 支持多种传输方式对于本地开发最常用的是stdio标准输入输出和SSEServer-Sent Events。Stdio 模式简单适合本地进程间通信SSE 则适用于网络场景。一次典型的调用流程如下初始化客户端启动服务器进程stdio或连接到服务器端点SSE。交换能力客户端与服务器交换初始化消息协商协议版本。列出工具/资源客户端请求服务器列出所有可用的工具和资源。调用工具用户通过客户端界面触发某个需求客户端选择对应的工具构造包含参数的请求发送给服务器。执行与返回服务器收到请求执行内部逻辑如运行代码、查询数据然后将结构化的结果文本、图片、数据等返回给客户端。呈现结果客户端将结果整合到对话或界面中完成一次交互。理解了这些我们就知道配置本地环境的本质是编写一个符合 MCP 协议的服务器程序并配置 AI 客户端以正确的方式启动或连接这个服务器。2. 环境准备与依赖配置我们将使用 Python 来开发 MCP 服务器因为它拥有成熟的 MCP SDK社区活跃示例丰富。请确保你的开发环境满足以下要求。2.1 基础环境检查清单在开始之前请依次检查并准备好以下项目项目要求检查命令说明操作系统Windows 10/11, macOS, Linux-主流系统均可本文以 macOS/Linux 命令为例Windows 用户请使用 PowerShell 或 WSL。Python版本 3.8 或更高python --version或python3 --version确保 Python 已正确安装并加入系统 PATH。包管理工具pippip --version通常随 Python 安装。建议升级至最新版pip install --upgrade pip。代码编辑器VS Code, PyCharm 等-推荐使用 VS Code 并安装 Python 扩展便于开发和调试。虚拟环境工具venv(推荐)python -m venv --help用于创建独立的 Python 环境避免包冲突。2.2 创建项目目录与虚拟环境为项目创建一个独立的目录并在其中初始化 Python 虚拟环境。这是保证依赖隔离的最佳实践。# 1. 创建项目目录并进入 mkdir tare-mcp-server cd tare-mcp-server # 2. 创建 Python 虚拟环境 # 在项目根目录下创建一个名为 .venv 的虚拟环境 python3 -m venv .venv # 3. 激活虚拟环境 # macOS/Linux: source .venv/bin/activate # Windows PowerShell: # .venv\Scripts\Activate.ps1 # Windows CMD: # .venv\Scripts\activate.bat # 激活后命令行提示符前通常会显示 (.venv)表示已进入虚拟环境。2.3 安装核心依赖MCP SDK我们将使用 Anthropic 官方维护的mcpPython 库它提供了编写服务器和客户端的底层协议实现以及一些高级工具。# 确保在激活的虚拟环境中执行 pip install mcp安装完成后可以验证一下版本python -c import mcp; print(fMCP SDK version: {mcp.__version__})除了基础 SDK我们可能还需要一些辅助库用于实现具体的服务器功能例如操作文件、处理 HTTP 请求等。这里我们先安装常用的几个pip install pydantic httpxpydantic用于数据验证和设置管理MCP SDK 内部也依赖它来定义模型。httpx一个现代的 HTTP 客户端库如果我们的服务器需要调用外部 API它会非常有用。至此基础的 Python 开发环境已经就绪。3. 构建你的第一个 MCP 服务器现在我们开始编写代码。目标是创建一个最简单的 MCP 服务器它提供一个工具和一个资源并通过 stdio 传输协议与客户端通信。3.1 项目结构与入口文件在项目根目录 (tare-mcp-server/) 下创建以下文件结构tare-mcp-server/ ├── .venv/ # Python 虚拟环境由上一步创建 ├── server.py # MCP 服务器主程序 ├── pyproject.toml # 项目元数据和依赖声明可选但推荐 └── README.md # 项目说明文档首先创建server.py文件这将是我们的服务器入口。3.2 编写服务器代码一个简单的示例以下代码实现了一个提供“获取服务器时间”工具和“服务器信息”资源的 MCP 服务器。#!/usr/bin/env python3 TARE 示例 MCP 服务器。 提供获取当前时间和服务器信息的功能。 import asyncio import json import time from typing import Any import mcp.server as mcp_server from mcp.server.models import InitializationOptions import mcp.server.stdio from mcp.types import Tool, Resource, TextContent # 创建服务器实例 server mcp_server.Server(tare-example-server) # 1. 定义一个工具获取当前时间 server.list_tools() async def handle_list_tools() - list[Tool]: 列出服务器提供的所有工具。 return [ Tool( nameget_current_time, description获取服务器的当前系统时间并格式化为可读字符串。, inputSchema{ type: object, properties: { format: { type: string, description: 时间格式例如 %Y-%m-%d %H:%M:%S。留空则使用默认格式。, default: %Y-%m-%d %H:%M:%S } } } ) ] server.call_tool() async def handle_call_tool(name: str, arguments: dict[str, Any] | None) - list[TextContent]: 处理工具调用请求。 if name get_current_time: # 获取参数如果没有提供则使用默认值 fmt arguments.get(format, %Y-%m-%d %H:%M:%S) if arguments else %Y-%m-%d %H:%M:%S current_time time.strftime(fmt, time.localtime()) return [TextContent(typetext, textf当前服务器时间{current_time})] else: # 如果收到未知工具名抛出错误 raise ValueError(f未知工具: {name}) # 2. 定义一个资源服务器信息 server.list_resources() async def handle_list_resources() - list[Resource]: 列出服务器提供的所有资源。 return [ Resource( urifile:///tare-server/info, nameTARE 服务器信息, description关于这个示例 MCP 服务器的基本信息。, mimeTypetext/plain ) ] server.read_resource() async def handle_read_resource(uri: str) - str: 读取指定 URI 的资源内容。 if uri file:///tare-server/info: info { name: TARE Example MCP Server, version: 0.1.0, author: TARE Developer, description: 这是一个用于演示 MCP 协议本地配置的示例服务器。 } return json.dumps(info, indent2, ensure_asciiFalse) else: raise ValueError(f未知资源 URI: {uri}) async def main(): 主异步函数启动服务器。 # 使用 stdio 作为传输层 async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): # 初始化选项可以设置服务器能力等 init_options InitializationOptions( server_nametare-example-server, server_version0.1.0 ) # 运行服务器开始处理客户端请求 await server.run( read_stream, write_stream, init_options ) if __name__ __main__: # 运行异步主函数 asyncio.run(main())3.3 代码关键点解析服务器实例server mcp_server.Server(tare-example-server)创建了一个 MCP 服务器实例名称用于标识。工具定义server.list_tools()装饰的函数用于向客户端宣告工具列表。每个Tool对象定义了工具的名称、描述和输入参数的模式JSON Schema。server.call_tool()装饰的函数是工具调用的实际处理器。它根据name参数判断调用哪个工具并从arguments中解析参数。资源定义server.list_resources()和server.read_resource()分别用于列出资源和读取资源内容。资源通过 URI 标识可以返回任意文本内容如 JSON、纯文本。传输协议mcp.server.stdio.stdio_server()创建了一个基于标准输入输出的传输通道。这是与本地客户端如 Claude Desktop通信的最简单方式。异步运行MCP SDK 基于asyncio因此主函数main()是异步的并使用asyncio.run()启动。这个服务器已经具备了 MCP 协议要求的基本能力。你可以直接运行它但它会等待来自 stdio 的客户端连接所以单独运行会挂起。我们需要一个客户端来测试它。4. 连接测试与 Claude Desktop 集成编写好服务器后下一步是配置一个 MCP 客户端来连接并使用它。我们将以 Claude Desktop 为例这是目前最流行的 MCP 客户端之一。4.1 配置 Claude Desktop 的 MCP 设置Claude Desktop 允许通过配置文件添加自定义 MCP 服务器。找到配置文件位置macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在请手动创建。编辑配置文件使用文本编辑器打开或创建上述路径的 JSON 文件。添加以下配置{ mcpServers: { tare-example: { command: /absolute/path/to/your/tare-mcp-server/.venv/bin/python, args: [ /absolute/path/to/your/tare-mcp-server/server.py ], env: { PYTHONUNBUFFERED: 1 } } } }重要参数说明tare-example你给这个服务器起的名字会在 Claude 界面中显示。command必须是 Python 解释器的绝对路径。这里指向了你项目虚拟环境中的python可执行文件。你可以通过在项目目录的虚拟环境中运行which python(macOS/Linux) 或where python(Windows) 来获取这个路径。args一个列表第一个元素是你的server.py脚本的绝对路径。env设置环境变量PYTHONUNBUFFERED1确保 Python 输出是实时、无缓冲的这对于 stdio 通信至关重要。注意Windows 用户的command路径可能类似C:\Users\YourName\path\to\tare-mcp-server\.venv\Scripts\python.exe并且路径中的反斜杠需要使用双反斜杠\\或正斜杠/进行转义。保存并重启 Claude Desktop保存配置文件后完全退出并重新启动 Claude Desktop 应用。4.2 验证连接与功能测试重启 Claude Desktop 后如果配置正确你应该能在与 Claude 的对话中看到变化。观察连接状态通常Claude 不会明确提示“MCP 服务器已连接”。但当配置正确时服务器进程会在后台启动。你可以通过系统活动监视器macOS或任务管理器Windows查看是否有额外的 Python 进程。测试工具调用在 Claude 的输入框中尝试输入“请使用get_current_time工具查看一下当前时间。” 或者更自然地说“现在几点了用你的工具查一下。”Claude 应该能识别到可用的工具并可能自动或在你的确认下调用它。调用成功后Claude 的回复中应包含类似“当前服务器时间2024-01-01 12:00:00”的信息。测试资源读取你可以尝试询问“告诉我一些关于你连接的 MCP 服务器的信息。” Claude 可能会尝试读取file:///tare-server/info这个资源并将 JSON 信息呈现给你。如果测试失败请跳转到第 6 节“常见问题排查”进行诊断。5. 进阶开发实现一个实用的数据库查询服务器基础示例跑通后我们来构建一个更贴近实际需求的服务器一个可以查询数据库的 MCP 服务器。这里我们使用 SQLite 作为示例数据库但原理适用于 MySQL、PostgreSQL 等。5.1 扩展项目依赖首先安装操作 SQLite 的库。pip install aiosqliteaiosqlite提供了 SQLite 的异步接口与我们的异步服务器框架更匹配。5.2 创建数据库与示例数据在项目根目录下创建一个init_db.py脚本用于初始化数据库和示例数据。# init_db.py import sqlite3 import os DB_PATH example.db def init_database(): # 如果数据库已存在先删除仅用于演示 if os.path.exists(DB_PATH): os.remove(DB_PATH) conn sqlite3.connect(DB_PATH) cursor conn.cursor() # 创建用户表 cursor.execute( CREATE TABLE users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE, age INTEGER ) ) # 插入示例数据 sample_users [ (张三, zhangsanexample.com, 28), (李四, lisiexample.com, 35), (王五, wangwuexample.com, 22), ] cursor.executemany(INSERT INTO users (name, email, age) VALUES (?, ?, ?), sample_users) conn.commit() conn.close() print(f数据库已初始化路径: {os.path.abspath(DB_PATH)}) if __name__ __main__: init_database()运行此脚本创建数据库python init_db.py5.3 编写数据库查询 MCP 服务器新建一个文件server_db.py实现数据库查询工具。# server_db.py import asyncio import aiosqlite from typing import Any import mcp.server as mcp_server from mcp.server.models import InitializationOptions import mcp.server.stdio from mcp.types import Tool, TextContent DB_PATH example.db server mcp_server.Server(tare-db-server) server.list_tools() async def handle_list_tools() - list[Tool]: return [ Tool( namequery_users, description查询用户表。可以通过姓名或年龄进行筛选。, inputSchema{ type: object, properties: { name_filter: { type: string, description: 按姓名模糊筛选可选。 }, min_age: { type: integer, description: 最小年龄可选。 }, max_age: { type: integer, description: 最大年龄可选。 }, limit: { type: integer, description: 返回结果的最大数量默认 10。, default: 10 } } } ), Tool( nameget_user_count, description获取用户表中的总记录数。, inputSchema{type: object, properties: {}} # 无参数 ) ] server.call_tool() async def handle_call_tool(name: str, arguments: dict[str, Any] | None) - list[TextContent]: async with aiosqlite.connect(DB_PATH) as conn: conn.row_factory aiosqlite.Row # 返回字典样式的行 if name query_users: # 构建查询参数 args arguments or {} name_filter args.get(name_filter) min_age args.get(min_age) max_age args.get(max_age) limit args.get(limit, 10) query SELECT id, name, email, age FROM users WHERE 11 params [] if name_filter: query AND name LIKE ? params.append(f%{name_filter}%) if min_age is not None: query AND age ? params.append(min_age) if max_age is not None: query AND age ? params.append(max_age) query LIMIT ? params.append(limit) cursor await conn.execute(query, params) rows await cursor.fetchall() await cursor.close() if not rows: return [TextContent(typetext, text未找到匹配的用户。)] # 格式化结果 result_lines [查询结果] for row in rows: result_lines.append(f- ID: {row[id]}, 姓名: {row[name]}, 邮箱: {row[email]}, 年龄: {row[age]}) return [TextContent(typetext, text\n.join(result_lines))] elif name get_user_count: cursor await conn.execute(SELECT COUNT(*) as count FROM users) row await cursor.fetchone() await cursor.close() count row[count] return [TextContent(typetext, textf用户表中共有 {count} 条记录。)] else: raise ValueError(f未知工具: {name}) async def main(): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): init_options InitializationOptions( server_nametare-db-server, server_version0.1.0 ) await server.run(read_stream, write_stream, init_options) if __name__ __main__: asyncio.run(main())5.4 更新 Claude Desktop 配置并测试修改 Claude Desktop 的配置文件指向新的数据库服务器。{ mcpServers: { tare-db: { command: /absolute/path/to/your/tare-mcp-server/.venv/bin/python, args: [ /absolute/path/to/your/tare-mcp-server/server_db.py ], env: { PYTHONUNBUFFERED: 1 } } } }重启 Claude Desktop 后你可以进行如下测试“查询一下所有用户。”“帮我找找名字里带‘张’的用户。”“年龄在 25 到 40 岁之间的用户有哪些”“现在用户表里总共有多少人”Claude 会识别query_users和get_user_count工具并构造相应的参数进行查询最后将数据库结果返回给你。6. 常见问题排查在配置和开发 MCP 服务器的过程中你可能会遇到以下问题。请按照此清单进行排查。6.1 服务器启动失败或客户端无法连接问题现象可能原因检查方式处理建议Claude Desktop 启动后无任何反应工具列表不出现。1. 配置文件路径或格式错误。2. Python 或脚本路径不正确。3. 虚拟环境未激活或依赖未安装。1. 检查claude_desktop_config.json文件是否在正确位置JSON 语法是否正确可使用在线校验器。2. 在终端中手动运行配置中的command和args看是否能启动 Python 并执行脚本。3. 检查虚拟环境中的mcp包是否安装pip list | grep mcp。1. 修正 JSON 文件。2. 使用绝对路径并确保路径中的空格已转义。3. 在项目目录下重新激活虚拟环境并安装依赖。启动 Claude 时系统提示“无法启动服务器”或类似错误。1. 命令执行权限不足。2. Python 脚本存在语法错误。3. 缺少必要的环境变量。1. 检查command指向的 Python 解释器是否有执行权限。2. 在终端直接运行python server.py查看是否有 Python 语法报错。3. 查看 Claude Desktop 的日志文件位置因系统而异通常在配置目录附近。1. 确保脚本和解释器可读可执行。2. 根据 Python 报错信息修正代码。3. 在配置的env字段中添加必要的变量如PYTHONPATH。6.2 工具调用失败或返回错误问题现象可能原因检查方式处理建议Claude 能识别工具但调用后返回“工具执行错误”或超时。1. 服务器端call_tool处理函数抛出未捕获的异常。2. 数据库连接失败或 SQL 错误。3. 参数解析失败。1. 这是最难调试的因为 stdio 模式下服务器日志不易查看。最佳方式是在server.py中使用logging模块将日志写入文件。2. 检查数据库文件路径、权限。3. 在handle_call_tool函数开始处打印name和arguments到日志文件。1.强烈建议添加文件日志。在main()函数前添加import logging; logging.basicConfig(filenamemcp_server.log, levellogging.DEBUG)并在关键位置logging.debug(...)。2. 确保数据库文件存在且 SQL 语法正确。3. 验证客户端发送的参数格式是否符合inputSchema的定义。工具调用成功但返回的结果格式混乱或 Claude 无法理解。服务器返回的内容不是有效的TextContent列表或包含特殊字符。检查handle_call_tool函数的返回值确保它返回的是List[TextContent]。对于纯文本使用TextContent(typetext, text你的结果)。确保返回的数据结构正确。如果返回复杂数据可以将其格式化为清晰的纯文本或 JSON 字符串。6.3 性能与稳定性问题问题现象可能原因检查方式处理建议工具调用响应缓慢。1. 服务器端操作如复杂查询、网络请求本身耗时。2. 数据库未建立索引。3. 每次调用都创建新的数据库连接。1. 在日志中记录工具调用的开始和结束时间。2. 分析 SQL 查询执行计划。3. 检查连接池是否被使用。1. 对于耗时操作考虑在工具描述中提醒用户。2. 为常用查询字段添加数据库索引。3. 使用连接池如aiosqlite的connect通常已优化但频繁开关连接仍有开销。服务器进程意外退出。1. 代码中存在未处理的异常导致进程崩溃。2. 系统资源不足。3. Claude Desktop 被关闭stdio 管道断开。1. 查看日志文件中是否有崩溃堆栈信息。2. 监控系统资源使用情况。1. 用try...except包裹工具执行逻辑并记录异常。2. 确保代码具有良好的错误处理机制避免因单次调用失败导致整个服务器崩溃。7. 生产环境考量与最佳实践本地开发环境跑通后若计划将 MCP 服务器部署到生产环境或供团队使用需要考虑以下方面。7.1 安全加固输入验证与净化永远不要信任客户端传入的参数。在数据库查询示例中我们使用了参数化查询 (?占位符) 来防止 SQL 注入。对于其他操作如文件路径、系统命令必须进行严格的验证和白名单过滤。权限控制MCP 服务器进程应以最小必要权限运行。避免使用 root 或管理员账户。认证与授权Stdio 模式通常用于可信本地环境。如果通过 SSE 暴露到网络必须实现认证机制如 API Key、JWT。MCP 协议本身不强制要求认证这需要服务器自行实现。敏感信息数据库密码、API Key 等不应硬编码在代码中。使用环境变量或配置管理服务如 Vault来管理。7.2 可观测性与运维结构化日志如前所述使用logging模块记录 INFO、ERROR 等级别的日志并输出到文件或日志收集系统如 ELK、Loki。记录每次工具调用的请求、响应和耗时。健康检查可以提供一个简单的工具如ping或资源供监控系统调用以检查服务器是否存活。版本管理在InitializationOptions中明确服务器版本便于客户端兼容性管理。资源清理确保数据库连接、网络会话等资源在使用后正确关闭避免泄漏。7.3 协议与客户端兼容性协议版本关注 MCP 协议版本的更新。SDK 通常会处理兼容性但了解新特性有助于改进服务器。多客户端支持除了 Claude Desktop你的服务器也可以被 Cursor、Windmill 等其他支持 MCP 的客户端使用。确保工具的描述清晰、通用避免依赖特定客户端的特性。优雅降级如果服务器依赖的外部服务如数据库、第三方 API不可用工具应返回明确的错误信息而不是崩溃。7.4 扩展方向更复杂的工具实现调用内部 API、发送邮件、生成图表、操作云资源等工具。动态资源资源内容可以不来自静态文件而是动态生成例如“当前系统状态报告”、“今日待办事项列表”。使用 SSE 传输学习配置基于 HTTP/SSE 的 MCP 服务器使其可以通过网络被远程调用。打包与分发考虑使用pyinstaller或docker将你的 MCP 服务器打包方便分发和部署。配置 MCP 本地环境的核心在于理解协议的角色分工服务器提供能力客户端消费能力。通过 Python MCP SDK我们可以快速将任何 Python 函数封装成 AI 可用的工具。从简单的系统信息查询到复杂的业务数据操作MCP 为 AI 应用接入现有系统提供了标准化、安全且强大的通道。成功的关键步骤可以总结为创建虚拟环境、安装 SDK、编写工具处理函数、通过 stdio 暴露服务、最后在 Claude Desktop 等客户端中正确配置。当遇到问题时系统地检查配置文件路径、依赖安装、代码逻辑和日志输出大部分问题都能迎刃而解。接下来你可以尝试将工作中重复性的查询、报告生成或系统状态检查任务封装成 MCP 工具让人工智能成为你日常工作流中一个高效、自然的助手。