本文翻译自 MCP 官方文档。

模型上下文协议 (MCP) 是一个开放协议，用于标准化应用程序如何向大语言模型 (LLM) 提供上下文信息。您可以将 MCP 视为 AI 应用的 USB-C 接口。正如 USB-C 提供了一种标准化的方式，将您的设备连接到各种外围设备和配件，MCP 也提供了一种标准化的途径，将 AI 模型连接到不同的数据源和工具。

为什么要使用 MCP？

MCP 能够帮助您在大语言模型 (LLM) 的基础上构建 AI 智能体 (AI Agent) 和复杂的工作流程。大语言模型 (LLM) 常常需要与数据和工具进行集成，而 MCP 提供了以下优势：

日益丰富的预构建集成方案，您的大语言模型 (LLM) 可以直接使用。
灵活切换不同大语言模型 (LLM) 提供商和供应商的能力。
在您的基础设施中安全地保护数据的最佳实践。

通用架构

从本质上讲，MCP 遵循客户端-服务器架构，其中宿主应用程序可以连接到多个服务器：

mcp

MCP 主机 (MCP Hosts)：希望通过 MCP 访问数据的应用程序，例如 Claude Desktop、集成开发环境 (IDE) 或 AI 工具。
MCP 客户端 (MCP Clients)：与服务器保持 1:1 连接的协议客户端。
MCP 服务器 (MCP Servers)：轻量级的程序，每个程序都通过标准化的模型上下文协议 (Model Context Protocol) 提供特定的功能。
本地数据源 (Local Data Sources)：您的计算机中的文件、数据库和服务，MCP 服务器可以安全地访问这些数据。
远程服务 (Remote Services)：通过互联网访问的外部系统 (例如，通过应用程序编程接口 (API))，MCP 服务器可以连接到这些系统。

面向服务端开发人员

开始构建你自己的服务器，以便在 Claude for Desktop 和其他客户端中使用。

在本教程中，我们将构建一个简单的模型上下文协议 (MCP) 天气服务器，并将其连接到一个主机，即 Claude for Desktop。我们将从一个基本设置开始，然后逐步发展到更复杂的使用案例。

我们将构建的内容

许多大语言模型 (包括 Claude) 目前不具备获取天气预报和恶劣天气警报的能力。让我们使用 MCP 来解决这个问题!

我们将构建一个服务器，它暴露两个工具：get-alerts 和 get-forecast。然后，我们将把该服务器连接到一个 MCP 主机 (在本例中是 Claude for Desktop)：

服务器可以连接到任何客户端。为了简单起见，我们在这里选择了 Claude for Desktop，但我们也有关于构建你自己的客户端的指南，以及一个其他客户端的列表。

为什么选择 Claude for Desktop 而不是 Claude.ai？

因为服务器是本地运行的，所以 MCP 目前只支持桌面主机。远程主机正在积极开发中。

核心 MCP 概念

MCP 服务器可以提供三种主要类型的能力：

资源：可以被客户端读取的类文件数据 (如 API 响应或文件内容)
工具：可以被大语言模型调用的函数 (需要用户批准)
提示：帮助用户完成特定任务的预写模板

本教程将主要关注工具 (Python)。

让我们开始构建我们的天气服务器吧！你可以在这里找到我们将要构建的完整代码。

前提知识

本快速入门假设你熟悉：

Python
像 Claude 这样的大语言模型

系统要求

安装了 Python 3.10 或更高版本。
你必须使用 Python MCP SDK 1.2.0 或更高版本。

设置你的环境

首先，让我们安装 uv 并设置我们的 Python 项目和环境：

MacOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

确保之后重启你的终端，以确保 uv 命令被识别。

现在，让我们创建并设置我们的项目：

MacOS/Linux

# 创建项目目录
uv init weather
cd weather

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装依赖
uv add "mcp[cli]" httpx

# 创建服务器文件
touch weather.py

现在让我们深入构建你的服务器。

构建你的服务器

导入包和设置实例

将这些添加到你的 weather.py 文件的顶部：

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# 初始化 FastMCP 服务器
mcp = FastMCP("weather")

# 常量
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

FastMCP 类使用 Python 类型提示和文档字符串来自动生成工具定义，从而轻松创建和维护 MCP 工具。

辅助函数

接下来，让我们添加我们的辅助函数，用于查询和格式化来自国家气象局 API 的数据：

async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

实现工具执行

工具执行处理程序负责实际执行每个工具的逻辑。让我们添加它：

@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."

    if not data["features"]:
        return "No active alerts for this state."

    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # First get the forecast grid endpoint
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    # Get the forecast URL from the points response
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    # Format the periods into a readable forecast
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # Only show next 5 periods
        forecast = f"""
{period['name']}:
Temperature: {period['temperature']}°{period['temperatureUnit']}
Wind: {period['windSpeed']} {period['windDirection']}
Forecast: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)

运行服务器

最后，让我们初始化并运行服务器：

if __name__ == "__main__":
    # 初始化并运行服务器
    mcp.run(transport='stdio')

你的服务器已完成！运行 uv run weather.py 以确认一切正常。

现在让我们从现有的 MCP 主机 Claude for Desktop 测试你的服务器。

使用 Claude for Desktop 测试你的服务器

Claude for Desktop 尚未在 Linux 上提供。Linux 用户可以继续阅读构建客户端教程，以构建连接到我们刚刚构建的服务器的 MCP 客户端。

首先，确保你已安装 Claude for Desktop。你可以在这里安装最新版本。如果你已经有 Claude for Desktop，请确保将其更新到最新版本。

我们需要为你想使用的任何 MCP 服务器配置 Claude for Desktop。为此，请在文本编辑器中打开位于 ~/Library/Application Support/Claude/claude_desktop_config.json 的 Claude for Desktop 应用程序配置。如果该文件不存在，请确保创建它。

例如，如果你安装了 VS Code：

MacOS/Linux

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

然后，你将在 mcpServers 键中添加你的服务器。只有正确配置了至少一个服务器，MCP UI 元素才会显示在 Claude for Desktop 中。

在这种情况下，我们将像这样添加我们的单个天气服务器：

MacOS/Linux

{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [\
                "--directory",\
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",\
                "run",\
                "weather.py"\
            ]
        }
    }
}

你可能需要在 command 字段中放入 uv 可执行文件的完整路径。你可以通过在 MacOS/Linux 上运行 which uv 或者在 Windows 上运行 where uv 来获取 uv 可执行文件的完整路径。

请确保传入服务器的绝对路径。

这告诉 Claude for Desktop：

有一个名为 “weather” 的 MCP 服务器
通过运行 uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py 来启动它

保存文件，然后重新启动 Claude for Desktop。

使用命令测试

让我们确保 Claude for Desktop 正在获取我们在 weather 服务器中暴露的两个工具。你可以通过查找锤子图标来做到这一点：

图 1:

单击锤子图标后，你应该会看到列出的两个工具：

图 2:

如果你的服务器未被 Claude for Desktop 识别，请继续阅读故障排除部分以获取调试提示。

如果锤子图标已显示，你现在可以通过在 Claude for Desktop 中运行以下命令来测试你的服务器：

萨克拉门托的天气怎么样？
德克萨斯州有哪些活跃的天气警报？

图 3:

图 4:

由于这是美国国家气象局，因此查询仅适用于美国地点。

幕后发生了什么

当你提出问题时：

客户端将你的问题发送给 Claude
Claude 分析可用的工具并决定使用哪些工具
客户端通过 MCP 服务器执行所选工具
结果被发送回 Claude
Claude 形成自然语言响应
响应显示给你！

故障排除

Claude for Desktop 集成问题

从 Claude for Desktop 获取日志

与 MCP 相关的 Claude.app 日志被写入 ~/Library/Logs/Claude 目录下的日志文件：

mcp.log 将包含有关 MCP 连接和连接失败的常规日志。
名为 mcp-server-SERVERNAME.log 的文件将包含来自命名服务器的错误 (stderr) 日志。

你可以运行以下命令来列出最近的日志并跟踪任何新日志：

# 查看 Claude 的日志以查找错误
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

服务器未在 Claude 中显示

检查你的 claude_desktop_config.json 文件语法
确保你的项目路径是绝对路径而不是相对路径
完整重启 Claude for Desktop

工具调用静默失败

如果 Claude 尝试使用这些工具但它们失败了：

检查 Claude 的日志是否存在错误
验证你的服务器构建和运行没有错误
尝试重启 Claude for Desktop

以上方法都不起作用，我该怎么办？

请参阅我们的调试指南以获取更好的调试工具和更详细的指导。

天气 API 问题

错误：无法检索网格点数据

这通常意味着：

坐标在美国境外
国家气象局 API 出现问题
你受到速率限制

修复方法：

验证你使用的是美国坐标
在请求之间添加一个小的延迟
检查国家气象局 API 状态页面

错误：[STATE] 没有活动警报

这不是错误 - 这只是意味着该州目前没有天气警报。尝试其他州或在恶劣天气期间检查。

有关更高级的故障排除，请查看我们的调试 MCP 指南

面向客户端开发人员

开始构建你自己的客户端，它可以与所有 MCP 服务器集成。

在本教程中，你将学习如何构建一个由大语言模型 (LLM) 驱动的聊天机器人客户端，该客户端可以连接到 MCP 服务器。建议您先阅读服务器快速入门，它将指导您完成构建第一个服务器的基础知识。

Python
Node
Java

你可以在这里找到本教程的完整代码。

系统要求

在开始之前，请确保您的系统满足以下要求：

Mac 或 Windows 电脑
已安装最新 Python 版本
已安装最新版本的 uv

设置你的环境

首先，使用 uv 创建一个新的 Python 项目：

# 创建项目目录
uv init mcp-client
cd mcp-client

# 创建虚拟环境
uv venv

# 激活虚拟环境
# 在 Windows 上：
.venv\Scripts\activate
# 在 Unix 或 MacOS 上：
source .venv/bin/activate

# 安装所需的包
uv add mcp anthropic python-dotenv

# 删除示例文件
rm hello.py

# 创建主文件
touch client.py

设置你的 API 密钥

你需要一个 Anthropic API 密钥，可以从 Anthropic Console 获取。如果没有账号，需要先注册一个账号并创建一个 API 密钥。

创建一个 .env 文件来存储你的 API 密钥：

# 创建 .env 文件
touch .env

将你的 API 密钥添加到 .env 文件：

ANTHROPIC_API_KEY=<your key here>

将 .env 文件添加到你的 .gitignore 文件中，防止 API 密钥泄露：

echo ".env" >> .gitignore

请务必妥善保管你的 ANTHROPIC_API_KEY！

创建客户端

基本客户端结构

首先，引入所需的模块，并创建基本的客户端类 MCPClient：

import asyncio
from typing import Optional
from contextlib import AsyncExitStack

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()  # 从 .env 文件加载环境变量

class MCPClient:
    def __init__(self):
        # 初始化会话和客户端对象
        self.session: Optional<ClientSession> = None
        self.exit_stack = AsyncExitStack()
        self.anthropic = Anthropic()
    # methods will go here

服务器连接管理

接下来，实现连接到 MCP 服务器的方法 connect_to_server：

async def connect_to_server(self, server_script_path: str):
    """连接到 MCP 服务器

    Args:
        server_script_path: 服务器脚本的路径 (.py 或 .js)
    """
    is_python = server_script_path.endswith('.py')
    is_js = server_script_path.endswith('.js')
    if not (is_python or is_js):
        raise ValueError("服务器脚本必须是 .py 或 .js 文件")

    command = "python" if is_python else "node"
    server_params = StdioServerParameters(
        command=command,
        args=[server_script_path],
        env=None
    )

    stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
    self.stdio, self.write = stdio_transport
    self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))

    await self.session.initialize()

    # 列出可用的工具
    response = await self.session.list_tools()
    tools = response.tools
    print("\nConnected to server with tools:", [tool.name for tool in tools])

查询处理逻辑

现在添加处理查询和处理工具调用的核心功能，实现 process_query 方法：

async def process_query(self, query: str) -> str:
    """使用 Claude 和可用的工具处理查询"""
    messages = [\
        {\
            "role": "user",\
            "content": query\
        }\
    ]

    response = await self.session.list_tools()
    available_tools = [{\
        "name": tool.name,\
        "description": tool.description,\
        "input_schema": tool.inputSchema\
    } for tool in response.tools]

    # 首次调用 Claude API
    response = self.anthropic.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1000,
        messages=messages,
        tools=available_tools
    )

    # 处理响应和工具调用
    final_text = []

    assistant_message_content = []
    for content in response.content:
        if content.type == 'text':
            final_text.append(content.text)
            assistant_message_content.append(content)
        elif content.type == 'tool_use':
            tool_name = content.name
            tool_args = content.input

            # 执行工具调用
            result = await self.session.call_tool(tool_name, tool_args)
            final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")

            assistant_message_content.append(content)
            messages.append({
                "role": "assistant",
                "content": assistant_message_content
            })
            messages.append({
                "role": "user",
                "content": [\
                    {\
                        "type": "tool_result",\
                        "tool_use_id": content.id,\
                        "content": result.content\
                    }\
                ]
            })

            # 从 Claude 获取下一个响应
            response = self.anthropic.messages.create(
                model="claude-3-5-sonnet-20241022",
                max_tokens=1000,
                messages=messages,
                tools=available_tools
            )

            final_text.append(response.content[0].text)

    return "\n".join(final_text)

交互式聊天界面

添加聊天循环 chat_loop 和资源清理功能 cleanup：

async def chat_loop(self):
    """运行一个交互式聊天循环"""
    print("\nMCP Client Started!")
    print("Type your queries or 'quit' to exit.")

    while True:
        try:
            query = input("\nQuery: ").strip()

            if query.lower() == 'quit':
                break

            response = await self.process_query(query)
            print("\n" + response)

        except Exception as e:
            print(f"\nError: {str(e)}")

async def cleanup(self):
    """清理资源"""
    await self.exit_stack.aclose()

主要入口点

最后，添加主要的执行逻辑到 main 函数：

async def main():
    if len(sys.argv) < 2:
        print("Usage: python client.py <path_to_server_script>")
        sys.exit(1)

    client = MCPClient()
    try:
        await client.connect_to_server(sys.argv[1])
        await client.chat_loop()
    finally:
        await client.cleanup()

if __name__ == "__main__":
    import sys
    asyncio.run(main())

你可以在这里找到完整的 client.py 文件。

关键组件详解

1. 客户端初始化

MCPClient 类初始化会话管理和 API 客户端
使用 AsyncExitStack 进行资源管理，确保资源正确释放
配置 Anthropic 客户端以进行 Claude 的交互

2. 服务器连接

支持 Python 和 Node.js 服务器
验证服务器脚本类型，确保文件类型正确
设置适当的通信通道，建立客户端与服务器的连接
初始化会话并列出可用的工具

3. 查询处理

维护对话上下文，记住之前的对话内容
处理 Claude 的响应和工具调用
管理 Claude 和工具之间的消息流动
将结果组合成一个连贯的响应

4. 交互式界面

提供一个简单的命令行界面
处理用户输入并显示响应
包括基本错误处理
允许平滑关闭流程

5. 资源管理

适当的资源清理，防止资源泄露
连接问题的错误处理
平滑关闭流程

常见自定义点

工具处理
- 修改 process_query() 方法以处理特定类型的工具
- 为工具调用添加自定义错误处理
- 实现工具特定的响应格式
响应处理
- 自定义工具结果的格式化方式
- 添加响应过滤或转换
- 实现自定义日志记录
用户界面
- 添加 GUI 或 Web 界面
- 实现丰富的控制台输出
- 添加命令历史记录或自动完成

运行客户端

要使用任何 MCP 服务器运行你的客户端，请执行以下命令：

uv run client.py path/to/server.py # Python 服务器
uv run client.py path/to/build/index.js # Node 服务器

如果你正在继续服务器快速入门中的天气教程，你的命令可能如下所示：python client.py .../weather/src/weather/server.py

客户端会：

连接到指定的服务器
列出可用的工具
启动一个交互式聊天会话，你可以在其中：
- 输入查询
- 查看工具执行
- 从 Claude 获取响应

以下是连接到服务器快速入门中的天气服务器时的界面示例：

工作原理

当你提交查询时：

客户端从服务器获取可用工具列表
你的查询与工具描述一起发送给 Claude
Claude 决定使用哪些工具（如果有）
客户端通过服务器执行任何请求的工具调用
结果被发送回 Claude
Claude 提供自然语言响应
响应显示给你

最佳实践

错误处理
- 始终将工具调用包装在 try-catch 块中
- 提供有意义的错误消息
- 优雅地处理连接问题
资源管理
- 使用 AsyncExitStack 进行资源清理
- 完成后关闭连接
- 处理服务器断开连接
安全
- 将 API 密钥安全地存储在 .env 文件中
- 验证服务器响应
- 对工具权限保持谨慎

故障排除

服务器路径问题

仔细检查你的服务器脚本的路径是否正确
如果相对路径不起作用，请使用绝对路径
对于 Windows 用户，建议使用正斜杠 (/)，或者使用未转义的反斜杠 (\)
验证服务器文件是否具有正确的扩展名（Python 为 .py，Node.js 为 .js）

正确路径用法的示例：

# 相对路径
uv run client.py ./server/weather.py

# 绝对路径
uv run client.py /Users/username/projects/mcp-server/weather.py

# Windows 路径（两种格式均有效）
uv run client.py C:/projects/mcp-server/weather.py
uv run client.py C:\\projects\\mcp-server\\weather.py

响应时间

第一个响应可能需要长达 30 秒才能返回
这是正常的，因为：
- 服务器需要初始化
- Claude 需要处理查询
- 工具正在执行
后续响应通常会更快
在此初始等待期间请不要中断该过程

常见错误消息

如果你看到：

FileNotFoundError: 检查你的服务器路径
Connection refused: 确保服务器正在运行并且路径正确
Tool execution failed: 验证是否设置了该工具所需的环境变量
Timeout error: 考虑增加客户端配置中的超时时间

面向 Claude Desktop 用户

开始在 Claude for Desktop 中使用预构建的服务器。

在本教程中，您将扩展 Claude for Desktop ，使其能够读取您计算机的文件系统、写入新文件、移动文件，甚至搜索文件。

不用担心，在执行这些操作之前，它会征求您的许可！

1. 下载 Claude for Desktop

首先下载 Claude for Desktop ，选择 macOS 或 Windows 版本。(目前 Claude for Desktop 尚不支持 Linux。)

按照安装说明进行操作。

如果您已经安装了 Claude for Desktop，请点击电脑屏幕顶部的 Claude 菜单，选择“检查更新…”，确保您的 Claude 为最新版本。

为什么选择 Claude for Desktop 而不是 Claude.ai 网页版？

因为服务器是本地运行的，所以模型上下文协议 (MCP, Model Context Protocol) 目前仅支持桌面主机。远程主机功能正在积极开发中。

2. 添加文件系统 MCP 服务器

为了添加文件系统功能，我们需要将预构建的文件系统 MCP 服务器 (Filesystem MCP Server) 安装到 Claude for Desktop。这只是由 Anthropic 和社区创建的众多服务器之一。

首先，打开您电脑屏幕顶部的 Claude 菜单，然后选择“设置…”。请注意，这里的设置不是 Claude 应用程序窗口内的帐户设置。

在 Mac 上，菜单应该如下图所示：

点击“设置”窗口左侧的“开发者”选项，然后点击“编辑配置”：

这将会创建一个配置文件，文件路径如下：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

如果之前没有创建过配置文件，现在会在您的文件系统中显示该文件。

用任意文本编辑器打开该配置文件，然后将其内容替换为以下代码 (适用于 macOS/Linux 和 Windows)：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [\
        "-y",\
        "@modelcontextprotocol/server-filesystem",\
        "/Users/username/Desktop",\
        "/Users/username/Downloads"\
      ]
    }
  }
}

请务必将代码中的 username 替换为您计算机的用户名。代码中的路径应该指向您希望 Claude 能够访问和修改的有效目录。默认设置为桌面和下载目录，您也可以根据需要添加更多路径。

此外，您的计算机需要安装 Node.js 才能保证正常运行。要验证您是否已安装 Node.js，请打开命令行工具：

在 macOS 上，从“应用程序”文件夹中打开“终端”
在 Windows 上，按 Windows + R 键，输入“cmd”，然后按 Enter 键

在命令行中，输入以下命令来验证 Node.js 是否已成功安装：

node --version

如果出现“command not found”或“node is not recognized”的错误提示，请从 nodejs.org 下载并安装 Node.js。

配置文件的工作原理

此配置文件指示 Claude for Desktop 在每次启动时启动哪些 MCP 服务器。在本例中，我们添加了一个名为“filesystem”的服务器，它将使用 Node.js 的 npx 命令来安装并运行 @modelcontextprotocol/server-filesystem。该服务器的详细信息请参考此处。它允许您在 Claude for Desktop 中访问您的文件系统。

命令权限

Claude for Desktop 将以您用户帐户的权限运行配置文件中的命令，并允许其访问您的本地文件。因此，请仅添加您理解并信任的命令。

3. 重新启动 Claude

更新配置文件后，您需要重新启动 Claude for Desktop。

重新启动后，您应该在输入框的右下角看到一个锤子图标：

点击锤子图标后，您应该能看到文件系统 MCP 服务器提供的工具：

如果 Claude for Desktop 没有检测到您的服务器，请参考故障排除部分获取调试建议。

4. 尝试一下！

现在您可以和 Claude 对话，并向它询问关于您文件系统的问题。 Claude 应该知道何时调用相关的工具。

您可以尝试向 Claude 提出以下问题：

你能写一首诗并保存到我的桌面吗？
我的下载文件夹里有哪些与工作相关的文件？
你能将我桌面上的所有图片移动到一个名为“Images”的新文件夹吗？

Claude 会根据需要调用相关工具，并在执行操作前征求您的批准：

故障排除

未显示服务器 / 未显示锤子图标

完全退出并重新启动 Claude for Desktop
检查 claude_desktop_config.json 文件的语法是否正确
确保 claude_desktop_config.json 文件中包含的文件路径是有效的绝对路径，而不是相对路径
查看日志以了解服务器未连接的原因
在命令行中，尝试手动运行服务器 (像在 claude_desktop_config.json 文件中一样替换 username)，查看是否出现错误 (适用于 MacOS/Linux 和 Windows)：

npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads

从 Claude for Desktop 获取日志

与 MCP 相关的 Claude.app 日志记录在以下位置的日志文件中：

macOS: ~/Library/Logs/Claude
Windows: %APPDATA%\Claude\logs
mcp.log 文件包含关于 MCP 连接和连接失败的常规日志。
mcp-server-SERVERNAME.log 文件包含来自指定服务器的错误 (stderr) 日志。

您可以运行以下命令来列出最近的日志，并跟踪新的日志 (在 Windows 上，只会显示最近的日志) (适用于 MacOS/Linux 和 Windows)：

# Check Claude's logs for errors
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

工具调用失败但没有提示

如果 Claude 尝试使用工具但失败，请执行以下操作：

检查 Claude 的日志中是否有错误
验证您的服务器构建和运行是否没有错误
尝试重新启动 Claude for Desktop

如果以上方法均无效，该怎么办？

请参阅我们的调试指南，获取更好的调试工具和更详细的指导。

Windows 上路径中的 ENOENT 错误和 `${APPDATA}`

如果配置的服务器无法加载，并且您在日志中看到引用路径中 ${APPDATA} 的错误，您可能需要在 claude_desktop_config.json 的 env 键中添加 %APPDATA% 的展开值：

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
      "BRAVE_API_KEY": "..."
    }
  }
}

完成此更改后，再次启动 Claude Desktop。

应全局安装 NPM

如果您尚未全局安装 NPM，则 npx 命令可能会继续失败。如果 NPM 已经全局安装，您会发现您的系统上存在 %APPDATA%\npm。如果没有，您可以通过运行以下命令全局安装 NPM：

npm install -g npm

服务端样例

本页展示了一系列示例服务器和具体实现。

这些服务器演示了模型上下文协议 (Model Context Protocol, MCP) 的强大功能和灵活性，使大语言模型 (Large Language Model, LLM) 能够安全地访问各种工具和数据源。

官方示例

以下是由官方提供的示例服务器，展示了 MCP 的核心功能和软件开发工具包 (SDK) 的使用方法：

数据和文件系统

Filesystem - 提供安全的文件操作，并支持自定义访问权限控制。
PostgreSQL - 提供只读数据库访问，并具备数据库结构检查功能。
SQLite - 提供数据库交互和商业分析功能。
Google Drive - 允许访问和搜索 Google Drive 中的文件。

开发工具

Git - 提供读取、搜索和操作 Git 仓库的工具。
GitHub - 提供仓库管理、文件操作以及 GitHub API 集成功能。
GitLab - 通过 GitLab API 集成，实现项目管理功能。
Sentry - 从 Sentry.io 检索和分析问题报告。

Web 和浏览器自动化

Brave Search - 使用 Brave Search API 进行网页搜索和本地搜索。
Fetch - 针对大语言模型优化，提供网页内容抓取功能。
Puppeteer - 提供浏览器自动化和网页抓取功能。

生产力和沟通

Slack - 提供频道管理和消息功能。
Google Maps - 提供位置服务、路线规划和地点信息查询功能。
Memory - 提供基于知识图谱的长期记忆系统。

AI 和专用工具

EverArt - 使用各种模型生成人工智能图像。
Sequential Thinking - 通过序列化思考解决复杂问题。
AWS KB Retrieval - 从 AWS 知识库中检索信息，使用 Bedrock Agent Runtime。

官方集成

以下 MCP 服务器由各公司维护，用于集成到他们的平台：

Axiom - 使用自然语言查询和分析日志、追踪和事件数据。
Browserbase - 在云端自动执行浏览器交互。
Cloudflare - 在 Cloudflare 上部署和管理应用。
E2B - 在安全的云沙箱中执行代码。
Neon - 与 Neon 无服务器 PostgreSQL 平台交互。
Obsidian Markdown Notes - 读取和搜索 Obsidian 笔记库中的 Markdown 笔记。
Qdrant - 利用 Qdrant 向量搜索引擎实现语义记忆功能。
Raygun - 访问崩溃报告和监控数据。
Search1API - 提供统一的 API 用于搜索、网页抓取和站点地图生成。
Stripe - 与 Stripe API 交互。
Tinybird - 与 Tinybird 无服务器 ClickHouse 平台交互。
Weaviate - 通过您的 Weaviate 集合启用 Agentic RAG (一种结合智能体和检索增强生成的技术)。

社区案例

不断增长的社区贡献的服务器扩展了 MCP 的能力：

Docker - 管理 Docker 容器、镜像、卷和网络。
Kubernetes - 管理 Kubernetes 的 Pod (Kubernetes 中最小的可部署单元)、Deployment (用于管理 Pod 的部署) 和 Service (用于暴露应用的网络服务)。
Linear - 提供项目管理和问题追踪功能。
Snowflake - 与 Snowflake 数据库交互。
Spotify - 控制 Spotify 播放和管理播放列表。
Todoist - 集成任务管理功能。

Note: 请注意，社区服务器未经测试，使用风险自负。它们与 Anthropic 公司无关，也不受其认可。

要查看完整的社区服务器列表，请访问 MCP 服务器仓库。

快速上手

使用示例服务器

基于 TypeScript 的服务器可以直接使用 npx 命令运行：

npx -y @modelcontextprotocol/server-memory

基于 Python 的服务器可以使用 uvx (推荐) 或 pip 安装和运行：

# 使用 uvx
uvx mcp-server-git

# 使用 pip
pip install mcp-server-git
python -m mcp_server_git

使用 Claude 进行配置

要将 MCP 服务器与 Claude 配合使用，请将其添加到您的配置文件中：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

客户端样例

以下列出了支持 MCP 集成的应用

本页概述了支持模型上下文协议 (Model Context Protocol, MCP) 的应用程序。不同的客户端对 MCP 的支持程度各不相同，与 MCP 服务器的集成也各有侧重。

功能支持矩阵

客户端	资源	提示词	工具	采样	根目录	注释
Claude Desktop App	✅	✅	✅	❌	❌	完全支持所有 MCP 功能
5ire	❌	❌	✅	❌	❌	支持工具。
BeeAI Framework	❌	❌	✅	❌	❌	在 AI 智能体工作流中支持工具。
Cline	✅	❌	✅	❌	❌	支持工具和资源。
Continue	✅	✅	✅	❌	❌	完全支持所有 MCP 功能
Cursor	❌	❌	✅	❌	❌	支持工具。
Emacs Mcp	❌	❌	✅	❌	❌	在 Emacs 编辑器中支持工具。
Firebase Genkit	⚠️	✅	✅	❌	❌	支持通过工具进行资源列表的检索和查找。
GenAIScript	❌	❌	✅	❌	❌	支持工具。
Goose	❌	❌	✅	❌	❌	支持工具。
LibreChat	❌	❌	✅	❌	❌	支持 AI 智能体的工具
mcp-agent	❌	❌	✅	⚠️	❌	支持工具、服务器连接管理和 AI 智能体工作流。
oterm	❌	❌	✅	❌	❌	支持工具。
Roo Code	✅	❌	✅	❌	❌	支持工具和资源。
Sourcegraph Cody	✅	❌	❌	❌	❌	通过 OpenCTX 支持资源
Superinterface	❌	❌	✅	❌	❌	支持工具
TheiaAI/TheiaIDE	❌	❌	✅	❌	❌	支持 Theia AI 和 AI 驱动的 Theia IDE 中 AI 智能体的工具
Windsurf Editor	❌	❌	✅	❌	❌	通过 AI Flow 支持工具，用于协同开发。
Zed	❌	✅	❌	❌	❌	提示词显示为斜杠命令
SpinAI	❌	❌	✅	❌	❌	支持 Typescript AI 智能体的工具
OpenSumi	❌	❌	✅	❌	❌	在 OpenSumi 中支持工具
Daydreams Agents	✅	✅	✅	❌	❌	支持将服务器拖放到 Daydreams 智能体中

客户端详细信息

Claude Desktop App

Claude 桌面应用程序全面支持 MCP，可以与本地工具和数据源深度集成。

主要特点：

完整支持资源，允许附加本地文件和数据
支持提示词模板
支持工具集成，用于执行命令和脚本
支持本地服务器连接，从而增强隐私和安全性

ⓘ 注意：Claude.ai 网页应用目前不支持 MCP。MCP 功能仅在桌面应用程序中可用。

5ire

5ire 是一个开源的跨平台桌面 AI 助手，通过 MCP 服务器支持各种工具的使用。

主要特点：

内置 MCP 服务器，可以快速启用和禁用。
允许用户通过修改配置文件来添加更多服务器。
开源且用户友好，适合新手使用。
未来将不断改进对 MCP 的支持。

BeeAI Framework

BeeAI Framework 是一个开源框架，用于大规模构建、部署和提供强大的 AI 智能体工作流服务。该框架包含一个原生功能 MCP 工具，可以简化 MCP 服务器与 AI 智能体工作流的集成。

主要特点：

将 MCP 工具无缝集成到 AI 智能体工作流中。
从连接的 MCP 客户端快速实例化框架原生工具。
计划未来支持更多 AI 智能体相关的 MCP 功能。

了解更多：

查看在 AI 智能体工作流中使用 MCP 工具的示例 (链接到 BeeAI Framework 的文档)

Cline

Cline 是一款在 VS Code 中运行的自主编码 AI 智能体，可以编辑文件、运行命令、使用浏览器等等，每一步操作都会征得您的许可。

主要特点：

支持通过自然语言创建和添加工具（例如，“添加一个搜索网络的工具”）
允许通过 ~/Documents/Cline/MCP 目录与他人共享 Cline 创建的自定义 MCP 服务器
可以显示配置的 MCP 服务器及其关联的工具、资源和错误日志

Continue

Continue 是一款开源 AI 代码助手，内置支持所有 MCP 功能。

主要特点

键入“@”以提及 MCP 资源
提示词模板以斜杠命令的形式出现
支持直接在聊天界面中使用内置工具和 MCP 工具
支持 VS Code 和 JetBrains IDE 等多种集成开发环境，并兼容各类大语言模型

Cursor

Cursor 是一款 AI 代码编辑器。

主要特点：

在 Cursor Composer 中支持 MCP 工具
支持 STDIO 和 SSE 两种数据传输方式

Emacs Mcp

Emacs Mcp 是一款 Emacs 客户端，旨在与 MCP 服务器连接，实现无缝连接和交互。它为 AI 插件（如 gptel 和 llm）提供 MCP 工具调用支持，遵循 Emacs 的标准工具调用格式，从而增强 Emacs 生态系统中 AI 工具的功能。

主要特点：

为 Emacs 提供 MCP 工具支持。

Firebase Genkit

Genkit 是 Firebase 的软件开发工具包 (SDK)，用于构建 GenAI 功能并将其集成到应用程序中。genkitx-mcp 插件支持将 MCP 服务器作为客户端使用，或者从 Genkit 工具和提示词创建 MCP 服务器。

主要特点：

客户端支持工具和提示词 (部分支持资源)
具有强大的发现功能，在 Genkit 的 Dev UI 游乐场中提供支持
与 Genkit 现有工具和提示词无缝互操作
适用于来自顶级供应商的各种生成式 AI 模型

GenAIScript

GenAIScript (使用 JavaScript) 以编程方式组合用于大语言模型 (LLM) 的提示词，并在 JavaScript 中协调 LLM、工具和数据。

主要特点：

提供用于处理提示词的 JavaScript 工具箱
抽象化复杂性，提高开发效率
与 Visual Studio Code 无缝集成

Goose

Goose 是一款开源 AI 智能体，通过自动化编码任务来增强软件开发能力。

主要特点：

通过工具将 MCP 功能公开给 Goose。
可以通过扩展目录、命令行界面 (CLI) 或用户界面 (UI) 直接安装 MCP。
允许通过构建自己的 MCP 服务器来扩展 Goose 的功能。
包括用于开发、Web 抓取、自动化、内存以及与 JetBrains 和 Google Drive 集成的内置工具。

LibreChat

LibreChat 是一款开源、可定制的 AI 聊天用户界面，支持多个 AI 提供商，现在也集成了 MCP。

主要特点：

通过 MCP 服务器扩展当前的工具生态系统，包括代码解释器和图像生成工具
使用来自顶级供应商的各种 LLM，将工具添加到可自定义的 AI 智能体
开源且支持自托管，具有安全的多用户支持
未来路线图包括扩展 MCP 功能支持

mcp-agent

mcp-agent 是一个简单且可组合的框架，用于使用模型上下文协议构建 AI 智能体。

主要特点：

自动管理 MCP 服务器的连接。
将来自多个服务器的工具公开给 LLM。
实现了构建有效 AI 智能体中定义的各种模式。
支持工作流暂停/恢复信号，例如等待人工反馈。

oterm

oterm 是一款 Ollama 的终端客户端，允许用户创建聊天会话或 AI 智能体。

主要特点：

支持与连接了工具的 Ollama 进行多次完全可定制的聊天会话。
支持 MCP 工具。

Roo Code

Roo Code 通过 MCP 提供 AI 编码辅助功能。

主要特点：

支持 MCP 工具和资源
与开发工作流集成
可扩展的 AI 功能

Sourcegraph Cody

Cody 是 Sourcegraph 的 AI 编码助手，通过 OpenCTX 实现 MCP。

主要特点：

支持 MCP 资源
与 Sourcegraph 的代码智能功能集成
使用 OpenCTX 作为抽象层
计划未来支持更多 MCP 功能

SpinAI

SpinAI 是一个开源的 TypeScript 框架，用于构建可观测的 AI 智能体。该框架提供原生的 MCP 兼容性，允许 AI 智能体与 MCP 服务器和工具无缝集成。

主要特点：

AI 智能体的内置 MCP 兼容性
开源的 TypeScript 框架
可观测的智能体架构
本机支持 MCP 工具集成

Superinterface

Superinterface 提供 AI 基础设施和开发者平台，用于构建应用内 AI 助手，支持 MCP、交互式组件、客户端函数调用等功能。

主要特点：

在通过 React 组件或脚本标签嵌入的助手中，可以使用来自 MCP 服务器的工具
支持服务器发送事件 (SSE) 传输
可以使用来自任何 AI 提供商 (OpenAI、Anthropic、Ollama 等) 的任何 AI 模型

TheiaAI/TheiaIDE

Theia AI 是一个用于构建 AI 增强工具和集成开发环境 (IDE) 的框架。AI 驱动的 Theia IDE 是一款基于 Theia AI 构建的开放且灵活的开发环境。

主要特点：

工具集成：Theia AI 使 AI 智能体 (包括 Theia IDE 中的智能体) 能够利用 MCP 服务器进行无缝工具交互。
可自定义的提示词：Theia IDE 允许用户定义和调整提示词，动态集成 MCP 服务器以实现定制的工作流。
自定义智能体：Theia IDE 支持创建利用 MCP 功能的自定义智能体，从而使用户能够动态设计专用工作流。

Theia AI 和 Theia IDE 的 MCP 集成为用户提供了极大的灵活性，使其成为探索和适应 MCP 的强大平台。

了解更多：

Windsurf Editor

Windsurf Editor 是一款 AI 智能体 IDE，将 AI 辅助功能与开发人员工作流相结合。它具有创新的 AI Flow 系统，该系统支持协作式和独立式 AI 交互，同时保持开发人员的控制。

主要特点：

革命性的 AI Flow 范例，实现人机协作
智能代码生成和理解
具有多模型支持的丰富开发工具

Zed

Zed 是一款高性能代码编辑器，内置 MCP 支持，专注于提示词模板和工具集成。

主要特点：

提示词模板在编辑器中显示为斜杠命令
用于增强编码工作流的工具集成
与编辑器功能和工作区上下文紧密集成
不支持 MCP 资源

OpenSumi

OpenSumi 是一个框架，可帮助您快速构建 AI 原生 IDE 产品。

主要特点：

在 OpenSumi 中支持 MCP 工具
支持内置 IDE MCP 服务器和自定义 MCP 服务器

Daydreams

Daydreams 是一个生成式智能体框架，用于在链上执行任何操作

主要特点：

支持配置文件中的 MCP 服务器
公开 MCP 客户端

向您的应用程序添加 MCP 支持

如果您已经为您的应用程序添加了 MCP 支持，请提交拉取请求，将其添加到此列表中。MCP 集成可以为您的用户提供强大的上下文感知 AI 功能，并使您的应用程序成为不断壮大的 MCP 生态系统的一部分。

添加 MCP 支持的益处：

允许用户携带他们自己的上下文信息和工具
加入不断增长的、可互操作的 AI 应用程序生态系统
为用户提供灵活的集成选项
支持本地优先的 AI 工作流

要开始在您的应用程序中实施 MCP，请查阅我们的 Python SDK 文档或 TypeScript SDK 文档。

更新与更正

此列表由社区维护。如果您发现任何不准确之处，或者想要更新您的应用程序对 MCP 支持的相关信息，请提交拉取请求，或在我们的文档仓库中开启 Issue。

为什么要使用 MCP？#

通用架构#

面向服务端开发人员#

我们将构建的内容#

核心 MCP 概念#

前提知识#

系统要求#

设置你的环境#

构建你的服务器#

导入包和设置实例#

辅助函数#

实现工具执行#

运行服务器#

使用 Claude for Desktop 测试你的服务器#

​ 使用命令测试#

​ 幕后发生了什么#

​ 故障排除#

面向客户端开发人员#

系统要求#

设置你的环境#

设置你的 API 密钥#

创建客户端#

基本客户端结构#

服务器连接管理#

查询处理逻辑#

交互式聊天界面#

主要入口点#

关键组件详解#

1. 客户端初始化#

2. 服务器连接#

3. 查询处理#

4. 交互式界面#

5. 资源管理#

常见自定义点#

运行客户端#

工作原理#

最佳实践#

故障排除#

服务器路径问题#

响应时间#

常见错误消息#

面向 Claude Desktop 用户#

1. 下载 Claude for Desktop#

2. 添加文件系统 MCP 服务器#

3. 重新启动 Claude#

4. 尝试一下！#

故障排除#

服务端样例#

官方示例#

数据和文件系统#

开发工具#

Web 和浏览器自动化#

生产力和沟通#

AI 和专用工具#

官方集成#

社区案例#

快速上手#

使用示例服务器#

使用 Claude 进行配置#

更多资源#

客户端样例#

​ 功能支持矩阵#

​ 客户端详细信息#

​ Claude Desktop App#

​ 5ire#

​ BeeAI Framework#

​ Cline#

​ Continue#

​ Cursor#

​ Emacs Mcp#

​ Firebase Genkit#

​ GenAIScript#

​ Goose#

​ LibreChat#

​ mcp-agent#

​ oterm#

​ Roo Code#

​ Sourcegraph Cody#

​ SpinAI#

​ Superinterface#

为什么要使用 MCP？

通用架构

面向服务端开发人员

我们将构建的内容

核心 MCP 概念

前提知识

系统要求

设置你的环境

构建你的服务器

导入包和设置实例

辅助函数

实现工具执行

运行服务器

使用 Claude for Desktop 测试你的服务器

使用命令测试

幕后发生了什么

故障排除

面向客户端开发人员

系统要求

设置你的环境

设置你的 API 密钥

创建客户端

基本客户端结构

服务器连接管理

查询处理逻辑

交互式聊天界面

主要入口点

关键组件详解

1. 客户端初始化

2. 服务器连接

3. 查询处理

4. 交互式界面

5. 资源管理

常见自定义点

运行客户端

工作原理

最佳实践

故障排除

服务器路径问题

响应时间

常见错误消息

面向 Claude Desktop 用户

1. 下载 Claude for Desktop

2. 添加文件系统 MCP 服务器

3. 重新启动 Claude

4. 尝试一下！

故障排除

服务端样例

官方示例

数据和文件系统

开发工具

Web 和浏览器自动化

生产力和沟通

AI 和专用工具

官方集成

社区案例

快速上手

使用示例服务器

使用 Claude 进行配置

更多资源

客户端样例

功能支持矩阵

客户端详细信息

Claude Desktop App

5ire

BeeAI Framework

Cline

Continue

Cursor

Emacs Mcp

Firebase Genkit

GenAIScript

Goose

LibreChat

mcp-agent

oterm

Roo Code

Sourcegraph Cody

SpinAI

Superinterface