MCP在Claude中使用

写好 MCP Server 后，怎么让它真正用起来？本篇详细讲在 Claude Desktop 和 Claude Code 中接入 MCP Server 的完整流程。

1. Claude Desktop 接入

配置文件位置

操作系统	配置文件路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

第一次配置如果文件不存在，需要手动创建。

基础结构

{
  "mcpServers": {
    "server-name-1": { /* 配置 1 */ },
    "server-name-2": { /* 配置 2 */ }
  }
}

server-name 是你给 Server 起的别名，会显示在 Claude Desktop 工具列表中。

stdio Server 配置

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/Documents"
      ]
    },
    "my-python-server": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "API_KEY": "your-key"
      }
    },
    "my-uv-server": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/project",
        "run", "server.py"
      ]
    }
  }
}

Streamable HTTP Server 配置

{
  "mcpServers": {
    "remote-api": {
      "url": "https://my-server.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

完全退出后重启

修改配置后必须完全退出 Claude Desktop：

macOS：菜单栏 Claude → Quit Claude（不是 Cmd+W）
Windows：右键托盘图标 → Quit
重启后才会加载新配置

2. 验证 Server 是否连接

启动 Claude Desktop 后，对话框右下角会有一个 🔌 图标：

点击图标看到所有已连接的 Server
每个 Server 下展示其提供的 Tools / Resources / Prompts
红色叹号表示连接失败，鼠标悬停看错误信息

3. Claude Desktop 中使用工具

自动调用 Tool

直接用自然语言提问，Claude 会自动决定调用哪个工具：

"帮我列一下 Documents 目录下的文件"

第一次调用某个工具时，会弹出权限对话框：

Allow once：只本次允许
Allow always：永久允许
Don't allow：拒绝

选择 Resource

点击对话框中的 📎 图标，可以从 Server 的资源列表中选择，附加到当前对话。

触发 Prompt

输入 /，会弹出所有可用的 Prompt 命令，选择后填入参数即可。

4. Claude Code 接入

Claude Code 是 Anthropic 的命令行 AI 编程工具，对 MCP 支持非常完善。

添加 Server

# 添加本地 stdio Server
claude mcp add my-server python /path/to/server.py

# 添加远程 HTTP Server
claude mcp add --transport http remote-server https://my-server.com/mcp

# 带环境变量
claude mcp add --env API_KEY=xxx my-server python server.py

列出已有 Server

claude mcp list

删除 Server

claude mcp remove my-server

配置文件

Claude Code 的 MCP 配置存在 ~/.claude.json：

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

5. 项目级配置（推荐团队场景）

Claude Code 支持项目级 MCP 配置，团队成员能共享：

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "project-db": {
      "command": "python",
      "args": ["./scripts/db_mcp.py"]
    }
  }
}

提交到 git，团队所有成员 clone 后自动获得相同的 MCP 配置。

6. 常用官方 Server 接入

文件系统

{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/path/to/allowed/directory"
    ]
  }
}

让 Claude 能在指定目录下读写文件。

GitHub

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
    }
  }
}

让 Claude 能查 PR、Issue、提交等。

PostgreSQL

{
  "postgres": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "postgresql://user:pass@localhost:5432/db"
    ]
  }
}

让 Claude 能直接查数据库。

Slack

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "xoxb-...",
      "SLACK_TEAM_ID": "T..."
    }
  }
}

完整官方 Server 列表见 github.com/modelcontextprotocol/servers。

7. 调试技巧

查看日志

客户端	日志路径
Claude Desktop (macOS)	`~/Library/Logs/Claude/mcp-server-*.log`
Claude Desktop (Windows)	`%APPDATA%\Claude\logs\mcp-server-*.log`
Claude Code	终端输出 + `~/.claude/logs/`

每个 Server 一个日志文件，包含：

启动信息
stderr 输出（你的 logging 内容）
错误堆栈

用 Inspector 单独测试

写完 Server 不要直接配进 Claude Desktop 测，先用 inspector：

mcp dev server.py

打开 Web 界面调试，确认所有 Tool/Resource/Prompt 工作正常后再接入。

验证 JSON 格式

claude_desktop_config.json 格式错误会导致 Claude Desktop 启动失败。可以用工具校验：

cat claude_desktop_config.json | jq .

或在 jsonlint.com 在线校验。

8. 常见问题

Q1：配置完没看到 Server

检查清单：

JSON 格式是否正确（用 jq 验证）
路径是否为绝对路径
完全退出 Claude Desktop 后重启
看日志文件中的错误信息

Q2：Server 一启动就退出

通常是命令找不到或脚本报错：

command 必须是系统 PATH 中的可执行文件
args 中的脚本路径用绝对路径
看 mcp-server-xxx.log 的具体错误

Q3：工具调用失败

看日志中的 stderr 输出
用 inspector 单独测试该工具
确认输入参数符合 schema

Q4：每次都要确认权限

第一次调用时选 "Always allow" 而不是 "Allow once"，会记住偏好。

Q5：Tool 太多模型用不准

模型上下文有限，单个会话注册超过 50 个 Tool 时模型会"挑花眼"。建议：

一个 Server 只暴露相关的几个 Tool
不要同时启用太多 Server
Tool 描述写得明确，帮助模型筛选

9. 安全建议

MCP Server 是真实代码，运行在你的机器上，要注意：

不要随意安装来路不明的 Server：等同于运行陌生的可执行文件
审查 Server 源码：开源 Server 至少瞄一眼实现
限制权限：文件系统 Server 只暴露必要目录
环境变量管理 secret：不要把 API key 硬编码进 Server 代码
本地优先：能本地解决的别上云

10. 一个完整接入示例

假设你写了一个 GitHub PR 分析的 Server github_pr_analyzer.py：

步骤 1：准备 Server

# github_pr_analyzer.py
import os
import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("github-pr-analyzer")

GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN")

@mcp.tool()
async def analyze_pr(owner: str, repo: str, pr_number: int) -> dict:
    """分析 GitHub PR 的改动情况"""
    headers = {"Authorization": f"Bearer {GITHUB_TOKEN}"}
    async with httpx.AsyncClient(headers=headers) as client:
        resp = await client.get(
            f"https://api.github.com/repos/{owner}/{repo}/pulls/{pr_number}"
        )
        pr = resp.json()
        return {
            "title": pr["title"],
            "additions": pr["additions"],
            "deletions": pr["deletions"],
            "changed_files": pr["changed_files"],
            "url": pr["html_url"],
        }

if __name__ == "__main__":
    mcp.run()

步骤 2：本地测试

mcp dev github_pr_analyzer.py

在 Inspector 中调用 analyze_pr，确认正常。

步骤 3：接入 Claude Desktop

{
  "mcpServers": {
    "github-pr": {
      "command": "python",
      "args": ["/Users/me/projects/github_pr_analyzer.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxx"
      }
    }
  }
}

步骤 4：重启 Claude Desktop，验证

发消息：

"帮我分析一下 anthropics/anthropic-sdk-python 的 PR #123"

Claude 自动调用 analyze_pr，返回结构化结果。

总结

Claude Desktop 配置文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json
Server 别名、command/args、env、url 等是核心配置项
修改配置必须完全退出后重启 Claude Desktop
Claude Code 用 claude mcp add/list/remove 命令管理
项目级 .mcp.json 适合团队共享配置
调试三板斧：看日志、用 inspector、校验 JSON
安全：审查 Server 代码、最小权限、用环境变量管理秘钥