---
title: "在 Claude Code 中配置 MCP"
wiki: mcp
category: "客户端集成"
slug: claude-code-setup
url: https://learnagent.wiki/mcp/cards/claude-code-setup
tags: ["MCP", "Claude Code", "CLI", "配置", "终端", "开发者"]
last_updated: 2026-04-11
reading_time: 17
---

> Claude Code 是 Anthropic 官方的**终端命令行工具**（CLI），你可以在终端里直接和 Claude 对话、让它帮你写代码、跑命令、管 Git。和 Claude Desktop 一样，Claude Code 也内置了完整的 MCP 支持，而且配置方式比 Desktop 更灵活——**不需要手动编辑 JSON 文件，用 `claude mcp add` 一条命令就能搞定**。

# 在 Claude Code 中配置 MCP

## 基础概念

Claude Code 是 Anthropic 官方的**终端命令行工具**（CLI），你可以在终端里直接和 Claude 对话、让它帮你写代码、跑命令、管 Git。和 Claude Desktop 一样，Claude Code 也内置了完整的 MCP 支持，而且配置方式比 Desktop 更灵活——**不需要手动编辑 JSON 文件，用 `claude mcp add` 一条命令就能搞定**。

如果你之前已经在 Claude Desktop 里配过 MCP Server，Claude Code 还支持一键导入，完全不用重新配置。

### 核心要素

| 要素 | 说明 |
|------|------|
| **配置命令** | `claude mcp add`，一行命令添加一个 Server |
| **三种传输方式** | stdio（本地进程）、HTTP（远程服务）、SSE（远程服务，旧版兼容） |
| **三种作用域** | local（当前项目私有）、project（团队共享）、user（全局通用） |
| **状态检查** | 对话中输入 `/mcp` 查看所有 Server 状态 |
| **OAuth 鉴权** | 远程 Server 支持 OAuth 2.0，在 `/mcp` 里一键授权 |

### 从添加到使用的完整流程

```mermaid
graph LR
    A["📦 claude mcp add"] --> B["✅ 配置写入"]
    B --> C["💬 启动 Claude Code"]
    C --> D["🔍 /mcp 查看状态"]
    D --> E["🔨 工具就绪"]
    E --> F["💬 自然语言调用"]
```

## 基础用法

### 第一步：确认 Claude Code 已安装

在终端运行：

```bash
claude --version
```

如果没有安装，运行以下命令全局安装：

```bash
npm install -g @anthropic-ai/claude-code
```

### 第二步：添加 MCP Server

Claude Code 支持三种传输方式，对应三种命令格式：

#### 方式一：添加远程 HTTP Server（推荐用于云端服务）

```bash
# 基本语法
claude mcp add --transport http <名称> <URL>

# 示例：连接 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 示例：带认证头
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"
```

#### 方式二：添加远程 SSE Server

```bash
# 基本语法
claude mcp add --transport sse <名称> <URL>

# 示例：连接 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 示例：带 API Key
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"
```

#### 方式三：添加本地 stdio Server

```bash
# 基本语法
claude mcp add --transport stdio <名称> --env 环境变量 -- <启动命令> [参数...]

# 示例：添加 PostgreSQL 数据库 Server
claude mcp add --transport stdio db \
  --env DATABASE_URL=postgresql://readonly:pass@localhost:5432/analytics \
  -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@localhost:5432/analytics"

# 示例：添加 Airtable Server
claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server
```

> **注意**：stdio 模式下，`--` 后面的内容就是启动 Server 的完整命令和参数。`--env` 用来传递环境变量。

### 第三步：查看和管理 Server

```bash
# 列出所有已配置的 Server
claude mcp list

# 查看某个 Server 的详细信息
claude mcp get notion

# 移除一个 Server
claude mcp remove notion

# 在 Claude Code 对话中查看 Server 运行状态
# 直接输入 /mcp
```

### 第四步：开始使用

启动 Claude Code 对话后，所有已配置 Server 的工具会自动可用：

```bash
claude
```

```text
你：帮我查一下 Sentry 最近 24 小时最常见的错误
Claude：[调用 Sentry MCP 工具查询]
Claude：最近 24 小时最常见的错误是...
```

### 进阶：从 Claude Desktop 导入配置

如果你之前已经在 Claude Desktop 里配好了 MCP Server，可以直接导入，不用重新写：

```bash
claude mcp add --from-claude-desktop
```

这会把 Claude Desktop 配置文件（`claude_desktop_config.json`）里的所有 Server 导入到 Claude Code。

### 进阶：把 Claude Code 自身当作 MCP Server

一个很有意思的功能——你可以让 Claude Code 暴露为 MCP Server，供其他应用（比如 Claude Desktop）调用：

```bash
# 在终端启动 Claude Code 作为 MCP Server
claude mcp serve
```

然后在 Claude Desktop 的配置文件里加上：

```json
{
  "mcpServers": {
    "claude-code": {
      "command": "claude",
      "args": ["mcp", "serve"]
    }
  }
}
```

这样 Claude Desktop 就能通过 MCP 调用 Claude Code 的能力（文件编辑、终端命令、代码搜索等），相当于让两个 Claude 实例协同工作。

## 三种作用域详解

MCP Server 可以配置在三个不同的作用域，决定谁能用、在哪用：

```mermaid
graph TB
    subgraph scopes["三种作用域"]
        L["📍 Local<br/>默认，当前项目私有<br/>存在 ~/.claude.json"]
        P["📂 Project<br/>团队共享<br/>存在项目根目录 .mcp.json"]
        U["👤 User<br/>全局通用<br/>存在 ~/.claude.json"]
    end
    scopes --> D{"怎么选？"}
    D -->|"个人实验、敏感凭证"| L
    D -->|"团队协作、项目工具"| P
    D -->|"跨项目通用工具"| U
```

| 作用域 | 存储位置 | 谁能用 | 适用场景 | 命令 |
|--------|---------|--------|---------|------|
| **local**（默认） | `~/.claude.json`（按项目路径） | 仅自己、仅当前项目 | 个人实验、含敏感凭证 | `claude mcp add --scope local ...` |
| **project** | 项目根目录 `.mcp.json` | 整个团队（可提交到 Git） | 团队共享工具 | `claude mcp add --scope project ...` |
| **user** | `~/.claude.json` | 仅自己、所有项目 | 个人常用工具 | `claude mcp add --scope user ...` |

**优先级**：local > project > user。同名 Server，local 配置覆盖 project 和 user。

### Project 作用域和 `.mcp.json`

当你使用 `--scope project` 时，Claude Code 会在项目根目录创建或更新 `.mcp.json` 文件：

```json
{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}
```

这个文件**可以提交到 Git**，团队成员 clone 仓库后自动拥有相同的 MCP 配置。为了安全，首次使用 project 作用域的 Server 时，Claude Code 会弹出确认框让你批准。

### 环境变量展开

`.mcp.json` 支持环境变量占位符，方便团队共享配置的同时保护敏感信息：

```json
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}
```

- `${VAR}` — 展开为环境变量 `VAR` 的值
- `${VAR:-default}` — 如果 `VAR` 未设置，使用 `default`

## 实用场景示例

### 场景一：监控线上错误（Sentry）

```bash
# 1. 添加 Sentry Server
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. 在对话中授权
# /mcp → 选择 Sentry → Authenticate

# 3. 使用
# "最近 24 小时最常见的错误是什么？"
# "帮我看一下 error ID abc123 的堆栈"
# "哪个部署引入了这些新错误？"
```

### 场景二：GitHub 代码审查

```bash
# 1. 添加 GitHub Server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 2. 在对话中授权
# /mcp → 选择 GitHub → Authenticate

# 3. 使用
# "帮我审查 PR #456，给出改进建议"
# "为这个 bug 创建一个新 issue"
# "看看分配给我的所有 open PR"
```

### 场景三：查询数据库（PostgreSQL）

```bash
# 1. 添加数据库 Server
claude mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/analytics"

# 2. 使用
# "这个月的总营收是多少？"
# "给我看一下 orders 表的结构"
# "找出 90 天内没下过单的客户"
```

### 场景四：企业批量管理

企业管理员可以部署 `managed-mcp.json` 统一管控所有员工的 MCP 配置，还可以用 allowlist/denylist 限制哪些 Server 允许使用：

```json
{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}
```

## 同类工具对比

| 维度 | Claude Code | Claude Desktop | Cursor | VS Code (Copilot Chat) |
|------|------------|---------------|--------|----------------------|
| 配置方式 | `claude mcp add` 命令行 | 编辑 JSON 文件 | Settings UI + JSON | `settings.json` |
| 传输方式 | stdio / HTTP / SSE | stdio / HTTP | stdio / HTTP | stdio / HTTP |
| 作用域管理 | local / project / user 三级 | 全局一份配置 | 项目级 + 全局 | 项目级 + 全局 |
| 团队共享 | `.mcp.json` 提交到 Git | 不支持 | `.cursor/mcp.json` | `.vscode/mcp.json` |
| OAuth 鉴权 | `/mcp` 内置授权流程 | 手动配置 Token | 内置授权 | 手动配置 |
| 导入已有配置 | 从 Claude Desktop 一键导入 | — | — | — |
| 自身当 Server | `claude mcp serve` | 不支持 | 不支持 | 不支持 |
| 适合谁 | 开发者、终端重度用户 | 日常对话、非技术用户 | 开发者（IDE 内） | 开发者（IDE 内） |

核心区别：

- **Claude Code**：配置最灵活，命令行一条搞定，支持三级作用域和团队共享，开发者首选
- **Claude Desktop**：MCP 支持最完整（含 Sampling、Elicitation），但配置需手动编辑 JSON
- **Cursor / VS Code**：MCP 深度集成在 IDE 工作流中，适合写代码场景

## 常见误区

| 误区 | 准确理解 |
|------|----------|
| 以为 Claude Code 和 Claude Desktop 配置互通 | 两者是独立的配置体系。Claude Code 用 `claude mcp add` 管理，Claude Desktop 用 JSON 文件。但 Code 支持从 Desktop 一键导入 |
| 以为改了配置要重启终端 | 不需要。直接在对话中输入 `/mcp` 刷新状态即可。只有首次添加新 Server 需要重新启动 `claude` |
| 以为 stdio Server 的 `--env` 和写在 `.mcp.json` 里效果一样 | 效果类似但作用域不同。`--env` 跟着命令走（local），`.mcp.json` 里的 `env` 是 project 级别可团队共享 |
| 以为 project 作用域会泄露 API Key | `.mcp.json` 支持环境变量占位符 `${API_KEY}`，团队配置里写占位符，每个人在自己机器上设置真实的环境变量值即可 |
| 以为 Claude Code 只能在项目目录下用 MCP | user 作用域（`--scope user`）的 Server 对所有项目生效。比如你配一个全局的 GitHub Server，在任何项目目录下都能用 |
| 以为远程 Server 必须手动配置 Token | 很多远程 Server 支持 OAuth 2.0。添加后在 `/mcp` 里点击 Authenticate，浏览器弹出授权页面，不需要手动复制 Token |

## 优劣势分析

| 优势 | 劣势 |
|------|------|
| **一条命令搞定**：`claude mcp add` 比 Claude Desktop 手动编辑 JSON 方便太多 | **纯终端界面**：没有图形化配置界面，不适合不习惯命令行的用户 |
| **三级作用域**：local / project / user 灵活管理，团队共享和个人私用互不干扰 | **不支持 Sampling 原语**：Claude Desktop 支持所有客户端原语（Sampling、Elicitation），Code 目前不支持 Sampling |
| **团队协作友好**：`.mcp.json` 提交到 Git，新成员 clone 就能用 | **环境变量依赖**：project 作用域的敏感信息依赖环境变量，忘记设置就会报错 |
| **从 Desktop 导入**：已有配置一键迁移，不用重写 | **stdio Server 进程管理**：本地 Server 崩溃后需要手动排查，不像 Desktop 有独立的日志文件 |
| **自身可当 Server**：`claude mcp serve` 让其他应用调用 Code 的能力，组合玩法多 | **企业管控学习曲线**：allowlist/denylist 配置规则较复杂，需要理解命令匹配和名称匹配的区别 |

## 思考题

<details>
<summary>初级：如果你想让 Claude Code 连接一个远程 Notion MCP Server，应该用什么命令？</summary>

**参考答案：**

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

这里选 HTTP 传输方式，因为 Notion 是云端服务，不是跑在本地的。添加成功后，启动 Claude Code 对话，输入 `/mcp` 检查 Notion Server 是否在线。如果需要授权，在 `/mcp` 界面点击 Authenticate，浏览器会弹出 Notion 的 OAuth 授权页面，授权完成后就能在对话中让 Claude 操作你的 Notion 数据了。

</details>

<details>
<summary>中级：local、project、user 三种作用域分别适合什么场景？如果团队里有 5 个人一起开发，推荐怎么配？</summary>

**参考答案：**

- **local**（默认）：个人在本项目下的实验性配置或含敏感凭证的 Server。只有你自己、只在这个项目目录下可见。
- **project**：团队共享的工具。配置写在 `.mcp.json`，提交到 Git，所有人 clone 仓库后自动拥有。
- **user**：你个人跨项目通用的工具。比如一个全局的 GitHub Server，在所有项目里都能用。

5 人团队推荐的配置策略：
1. 项目共用的 Server（如 Sentry、内部 API）用 **project** 作用域，配置写进 `.mcp.json`，API Key 用环境变量占位符 `${SENTRY_TOKEN}`，团队 Wiki 里记录每个人需要设置哪些环境变量
2. 个人偏好的工具（如你喜欢的某个数据库客户端）用 **user** 作用域
3. 含个人 Token 的临时实验用 **local** 作用域，避免误提交

这样既保证了团队工具的一致性，又尊重了每个人的个人偏好。

</details>

## 参考资料

1. Anthropic 官方文档 - Claude Code MCP 配置：<https://docs.anthropic.com/en/docs/claude-code/mcp>（查询日期 2026-04-11）
2. Claude Code 文档主页：<https://code.claude.com/docs/en/mcp>（查询日期 2026-04-11）
3. MCP 官方 - 连接本地 Server：<https://modelcontextprotocol.io/docs/develop/connect-local-servers>（查询日期 2026-04-11）
4. MCP 官方 - 连接远程 Server：<https://modelcontextprotocol.io/docs/develop/connect-remote-servers>（查询日期 2026-04-11）
5. Claude Code GitHub 仓库：<https://github.com/anthropics/claude-code>

---
*Source: https://learnagent.wiki/mcp/cards/claude-code-setup*
*Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*