Claude Code MCP 使用完全指南（本地 MCP + 远程 MCP）#

什么是 MCP？#

MCP（Model Context Protocol）可以理解为给 Claude 增加工具能力的能力：

MCP 架构原理#

1
Claude Code
2
      │
3
      ▼
4
 MCP Client
5
      │
6
 ┌────┴────┐
7
 │         │
8
 ▼         ▼
9
本地MCP    远程MCP
10
(stdio)   (http)
11
 │         │
12
 ▼         ▼
13
Playwright GitHub
14
SQLite     Notion
15
Redis      Sentry

配置文件位置#

Claude Code 有三个作用域：

本地 MCP（stdio）#

本地 MCP 由 Claude 启动子进程，通过 stdin/stdout 通信。典型应用：Playwright、SQLite、Redis、PostgreSQL。

1
# local（当前项目，默认）
2
claude mcp add playwright -- npx -y @playwright/mcp@latest
3

4
# project（团队共享，提交到 .mcp.json）
5
claude mcp add --scope project playwright -- npx -y @playwright/mcp@latest
6

7
# user（全局用户）
8
claude mcp add --scope user playwright -- npx -y @playwright/mcp@latest

1
claude mcp list              # 查看所有 MCP
2
claude mcp get playwright    # 查看详情
3
claude mcp remove playwright # 删除

1
{
2
  "mcpServers": {
3
    "playwright": {
4
      "type": "stdio",
5
      "command": "npx",
6
      "args": ["-y", "@playwright/mcp@latest"]
7
    }
8
  }
9
}

1
{
2
  "mcpServers": {
3
    "github": {
4
      "type": "stdio",
5
      "command": "npx",
6
      "args": ["-y", "@modelcontextprotocol/server-github"],
7
      "env": { "GITHUB_TOKEN": "ghp_xxxxxx" }
8
    }
9
  }
10
}

远程 MCP（HTTP）#

远程 MCP 通过 HTTP 连接云端服务器，不在本机运行。典型应用：GitHub MCP、Sentry MCP、Notion MCP、Claude Docs MCP。

1
claude mcp add \
2
  --transport http \
3
  claude-code-docs \
4
  https://code.claude.com/docs/mcp

1
{
2
  "mcpServers": {
3
    "claude-code-docs": {
4
      "type": "http",
5
      "url": "https://code.claude.com/docs/mcp"
6
    }
7
  }
8
}

1
Use claude-code-docs server to explain MCP_TIMEOUT

OAuth 登录型 MCP#

以 Sentry 为例：

1
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

安装后状态为 ! Needs authentication。在 Claude 中输入 /mcp，选择 sentry → Authenticate，浏览器授权后状态变为 ✓ Connected。

Token 登录型 MCP#

以 GitHub 为例：

1
claude mcp add \
2
  --transport http \
3
  github \
4
  https://api.githubcopilot.com/mcp \
5
  --header "Authorization: Bearer ghp_xxxxxx"

或 JSON 配置：

1
{
2
  "mcpServers": {
3
    "github": {
4
      "type": "http",
5
      "url": "https://api.githubcopilot.com/mcp",
6
      "headers": { "Authorization": "Bearer ghp_xxxxxx" }
7
    }
8
  }
9
}

团队共享 MCP#

使用 --scope project 让团队成员 clone 后自动获得 MCP：

1
claude mcp add --scope project playwright -- npx -y @playwright/mcp@latest

这会生成 .mcp.json，提交到 Git：

1
git add .mcp.json && git commit -m "Add MCP config" && git push

团队成员 git pull 后首次进入 Claude 会提示授权，同意即可。

常用 MCP 推荐#

1
claude mcp add playwright -- npx -y @playwright/mcp@latest