开始使用模型上下文协议 (MCP)介绍开始介绍复制页面开始使用模型上下文协议 (MCP) C# SDK 已发布！快

Build an MCP server that:
- Connects to my company's PostgreSQL database
- Exposes table schemas as resources
- Provides tools for running read-only SQL queries
- Includes prompts for common data analysis tasks

与克劳德合作

在 MCP 服务器上与 Claude 合作时：

首先从核心功能开始，然后迭代添加更多功能
要求 Claude 解释你不明白的代码部分
根据需要请求修改或改进
让 Claude 帮助您测试服务器并处理边缘情况

Claude 可以帮助实现所有关键的 MCP 功能：

资源管理和曝光
工具定义和实现
提示模板和处理程序
错误处理和日志记录
连接和传输设置

最佳实践

使用 Claude 构建 MCP 服务器时：

将复杂的服务器分解成更小的部分
继续操作之前彻底测试每个组件
牢记安全——验证输入并适当限制访问
为将来的维护做好代码记录
严格遵循 MCP 协议规范

后续步骤Next steps

在 Claude 帮助您构建服务器之后：

仔细检查生成的代码
使用 MCP Inspector 工具测试服务器
将其连接到 Claude.app 或其他 MCP 客户端
根据实际使用情况和反馈进行迭代

请记住，随着需求随时间的变化，Claude 可以帮助您修改和改进服务器。

需要更多指导？只需向 Claude 咨询有关实现 MCP 功能或故障排除的具体问题即可。

调试

调试模型上下文协议 (MCP) 集成的综合指南

在开发 MCP 服务器或将其与应用程序集成时，有效的调试至关重要。本指南介绍了 MCP 生态系统中可用的调试工具和方法。

本指南适用于 macOS。其他平台的指南即将推出。

调试工具概述

MCP 提供了几种用于不同级别调试的工具：

MCP 检查器
- 交互式调试界面
- 直接服务器测试
- 详情请参阅检查员指南
Claude桌面开发工具
- 集成测试
- 日志收集
- Chrome DevTools 集成
服务器日志
- 自定义日志记录实现
- 错误追踪
- 性能监控

在 Claude Desktop 中进行调试

检查服务器状态

Claude.app 界面提供了基本的服务器状态信息：

点击图标查看：
- 已连接的服务器
- 可用的提示和资源
点击图标查看：
- 为模型提供的工具

查看日志

查看 Claude Desktop 中的详细 MCP 日志：

# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

日志捕获：

服务器连接事件
配置问题
运行时错误
消息交换

使用 Chrome DevTools

访问 Claude Desktop 中的 Chrome 开发者工具来调查客户端错误：

创建一个设置developer_settings.json为 true 的文件allowDevTools：

echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
打开 DevTools：Command-Option-Shift-i

注意：您将看到两个 DevTools 窗口：

主内容窗口
应用程序标题栏窗口

使用控制台面板检查客户端错误。

使用网络面板检查：

消息有效载荷
连接时序

常见问题

工作目录

将 MCP 服务器与 Claude Desktop 结合使用时：

通过启动的服务器的工作目录claude_desktop_config.json可能未定义（例如/在 macOS 上），因为 Claude Desktop 可以从任何地方启动
始终在配置和.env文件中使用绝对路径以确保可靠运行
对于直接通过命令行测试服务器，工作目录将是您运行命令的位置

例如在中claude_desktop_config.json使用：

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}

而不是像这样的相对路径./data

环境变量

MCP 服务器仅自动继承一部分环境变量，如USER、HOME和PATH。

要覆盖默认变量或提供您自己的变量，您可以env在以下位置指定一个键claude_desktop_config.json：

{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

服务器初始化

常见的初始化问题：

路径问题
- 服务器可执行文件路径不正确
- 缺少必需文件
- 权限问题
- 尝试使用绝对路径command
配置错误
- JSON 语法无效
- 缺少必填字段
- 类型不匹配
环境问题
- 缺少环境变量
- 变量值不正确
- 权限限制

连接问题

当服务器连接失败时：

检查 Claude Desktop 日志
验证服务器进程是否正在运行
使用Inspector进行独立测试
验证协议兼容性

实现日志记录

服务器端日志记录

当构建使用本地 stdio传输的服务器时，记录到 stderr（标准错误）的所有消息将被主机应用程序（例如，Claude Desktop）自动捕获。

本地 MCP 服务器不应将消息记录到 stdout（标准输出），因为这会干扰协议操作。

对于所有传输，您还可以通过发送日志消息通知向客户端提供日志记录：

Python
TypeScript

server.request_context.session.send_log_message(
  level="info",
  data="Server started successfully",
)

要记录的重要事件：

初始化步骤
资源访问
工具执行
错误条件
性能指标

客户端日志记录

在客户端应用程序中：

启用调试日志记录
监控网络流量
跟踪消息交换
记录错误状态

调试工作流程

开发周期

初步开发
- 使用Inspector进行基本测试
- 实现核心功能
- 添加记录点
集成测试
- 在 Claude Desktop 中测试
- 监控日志
- 检查错误处理

测试更改

为了有效地测试更改：

配置更改：重新启动 Claude Desktop
服务器代码更改：使用 Command-R 重新加载
快速迭代：开发过程中使用Inspector

最佳实践

日志记录策略

结构化日志
- 使用一致的格式
- 包含上下文
- 添加时间戳
- 跟踪请求 ID
错误处理
- 记录堆栈跟踪
- 包含错误上下文
- 跟踪错误模式
- 监控恢复情况
绩效追踪
- 日志操作时序
- 监视资源使用情况
- 跟踪邮件大小
- 测量延迟

安全注意事项

调试时：

敏感数据
- 清理日志
- 保护凭证
- 掩盖个人信息
访问控制
- 验证权限
- 检查身份验证
- 监控访问模式

获取帮助

遇到问题时：

第一步
- 检查服务器日志
- 使用Inspector进行测试
- 查看配置
- 验证环境
支持渠道
- GitHub 问题
- GitHub 讨论
提供信息
- 日志摘录
- 配置文件
- 复现步骤
- 环境详细信息

后续步骤Next steps

MCP 检查器

学习使用 MCP 检查器

检查员

使用 MCP Inspector 测试和调试模型上下文协议服务器的深入指南

MCP Inspector是一款用于测试和调试 MCP 服务器的交互式开发者工具。虽然《调试指南》已将 Inspector 作为整个调试工具包的一部分进行了介绍，但本文档将详细介绍 Inspector 的功能和性能。

入门

安装和基本使用

Inspector 直接运行，npx无需安装：

npx @modelcontextprotocol/inspector <command>


npx @modelcontextprotocol/inspector <command> <arg1> <arg2>

从 NPM 或 PyPi 检查服务器

从NPM或PyPi启动服务器包的常用方法。

NPM 包
PyPi 包

npx -y @modelcontextprotocol/inspector npx <package-name> <args>
# For example
npx -y @modelcontextprotocol/inspector npx server-postgres postgres://127.0.0.1/testdb

检查本地开发的服务器

要检查本地开发或下载为存储库的服务器，最常见的方法是：

TypeScript
Python

npx @modelcontextprotocol/inspector node path/to/server/index.js args...

请仔细阅读任何附加的自述文件以获得最准确的说明。

功能概述

MCP 检查器界面

检查器提供了多种与 MCP 服务器交互的功能：

服务器连接窗格

允许选择连接到服务器的传输方式
对于本地服务器，支持自定义命令行参数和环境

资源选项卡

列出所有可用资源
显示资源元数据（MIME 类型、描述）
允许资源内容检查
支持订阅测试

“提示”选项卡

显示可用的提示模板
显示提示参数和描述
使用自定义参数启用快速测试
预览生成的消息

工具选项卡

列出可用的工具
显示工具模式和描述
使用自定义输入实现工具测试
显示工具执行结果

通知窗格

显示从服务器记录的所有日志
显示从服务器收到的通知

最佳实践

开发工作流程

开始开发
- 使用您的服务器启动 Inspector
- 验证基本连接
- 检查能力协商
迭代测试
- 进行服务器更改
- 重建服务器
- 重新连接检查器
- 测试受影响的功能
- 监视消息
测试边缘情况
- 无效输入
- 缺少提示参数
- 并发操作
- 验证错误处理和错误响应

对于服务器开发人员

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

在本教程中，我们将构建一个简单的 MCP 天气服务器，并将其连接到主机 Claude for Desktop。我们将从基本设置开始，然后逐步介绍更复杂的用例。

我们将要构建什么

目前，许多 LLM 课程无法获取天气预报和恶劣天气警报。让我们使用 MCP 来解决这个问题！

我们将构建一个服务器，其中包含两个工具：get-alerts和get-forecast。然后，我们将服务器连接到 MCP 主机（在本例中为 Claude for Desktop）：

服务器可以连接到任何客户端。为了简单起见，我们选择了 Claude for Desktop，但我们也提供了构建您自己的客户端的指南，以及其他客户端的列表。

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

核心 MCP 概念

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

资源：客户端可以读取的类似文件的数据（例如 API 响应或文件内容）
工具：可由 LLM 调用的函数（经用户批准）
提示：预先编写的模板，帮助用户完成特定任务

本教程将主要关注工具。

Python
Java
C#

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

预备知识

本快速入门假设您熟悉以下内容：

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

# Create a new directory for our project
uv init weather
cd weather

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx

# Create our server file
touch weather.py

现在让我们开始构建您的服务器。

构建你的服务器

导入包并设置实例

将这些添加到您的顶部weather.py：

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

# Initialize FastMCP server
mcp = FastMCP("weather")

# Constants
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__":
    # Initialize and run the server
    mcp.run(transport='stdio')

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

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

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

Claude 桌面版目前尚未在 Linux 上推出。Linux 用户可以继续学习构建客户端教程，构建一个连接到我们刚刚搭建的服务器的 MCP 客户端。

首先，请确保您已安装 Claude 桌面版。您可以点击此处安装最新版本。如果您已安装 Claude 桌面版，请确保将其更新至最新版本。

我们需要为您想要使用的 MCP 服务器配置 Claude for Desktop。为此，请在~/Library/Application Support/Claude/claude_desktop_config.json文本编辑器中打开您的 Claude for Desktop App 配置。如果该文件不存在，请务必创建。

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

MacOS/Linux

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

然后，您需要在密钥中添加服务器mcpServers。只有至少一台服务器正确配置后，MCP UI 元素才会显示在 Claude for Desktop 中。

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

MacOS/Linux

Python

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

uv您可能需要在字段中输入可执行文件的完整路径。您可以在 MacOS/Linux 或Windows 上command运行该程序来获取此信息。which uv``where uv

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

这告诉 Claude for Desktop：

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

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

使用命令进行测试

让我们确保 Claude for Desktop 能够获取我们在weather服务器中公开的两个工具。您可以通过查找锤子图标来执行此操作：

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

如果您的服务器未被 Claude for Desktop 接收，请继续执行故障排除部分以获取调试提示。

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

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

由于这是美国国家气象服务，因此查询仅适用于美国地区。

幕后发生了什么

当你问一个问题时：

客户将您的问题发送给 Claude
Claude 分析可用的工具并决定使用哪一个
客户端通过 MCP 服务器执行所选工具
结果发回给克劳德
克劳德制定了自然语言回应
答案已显示给您！

故障排除

Claude 桌面集成问题

天气 API 问题

开始使用模型上下文协议 (MCP)介绍

介绍

​为什么选择 MCP？

​总体架构

​开始

​快速入门

​示例

​教程

​探索 MCP

构建 MCP 并运用 LLM 进行学习

​准备文档

​描述您的服务器

​与克劳德合作

​最佳实践

​后续步骤Next steps

调试

​调试工具概述

​在 Claude Desktop 中进行调试

​检查服务器状态

​查看日志

​使用 Chrome DevTools

​常见问题

​工作目录

​环境变量

​服务器初始化

​连接问题

​实现日志记录

​服务器端日志记录

​客户端日志记录

​调试工作流程

​开发周期

​测试更改

​最佳实践

​日志记录策略

​安全注意事项

​获取帮助

​后续步骤Next steps

检查员

​入门

​安装和基本使用

​从 NPM 或 PyPi 检查服务器

​检查本地开发的服务器

​功能概述

​服务器连接窗格

​资源选项卡

​“提示”选项卡

​工具选项卡

​通知窗格

​最佳实践

​开发工作流程

对于服务器开发人员

​我们将要构建什么

​核心 MCP 概念

​预备知识

​系统要求

​设置您的环境

​构建你的服务器

​导入包并设置实例

​辅助函数

​实现工具执行

​运行服务器

​使用 Claude for Desktop 测试您的服务器

​使用命令进行测试

​幕后发生了什么

​故障排除

为什么选择 MCP？

总体架构

开始

快速入门

示例

教程

探索 MCP

准备文档

描述您的服务器

与克劳德合作

最佳实践

后续步骤Next steps

调试工具概述

在 Claude Desktop 中进行调试

检查服务器状态

查看日志

使用 Chrome DevTools

常见问题

工作目录

环境变量

服务器初始化

连接问题

实现日志记录

服务器端日志记录

客户端日志记录

调试工作流程

开发周期

测试更改

最佳实践

日志记录策略

安全注意事项

获取帮助

后续步骤Next steps

入门

安装和基本使用

从 NPM 或 PyPi 检查服务器

检查本地开发的服务器

功能概述

服务器连接窗格

资源选项卡

“提示”选项卡

工具选项卡

通知窗格

最佳实践

开发工作流程

我们将要构建什么

核心 MCP 概念

预备知识

系统要求

设置您的环境

构建你的服务器

导入包并设置实例

辅助函数

实现工具执行

运行服务器

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

使用命令进行测试

幕后发生了什么

故障排除