12.2 MCP 安装范围

第 12 章 · MCP 服务器配置与管理 · 第4部分：模型上下文协议 MCP

MCP 服务器可以在三个不同的范围级别进行配置，每个级别都用于管理服务器可访问性和共享的不同目的。

本地范围#

概述#

本地范围的服务器代表默认配置级别，存储在您的项目特定用户设置中。这些服务器对您保持私密，仅在当前项目目录中工作时可访问。

适用场景#

  • 个人开发服务器
  • 实验配置
  • 包含敏感凭证的服务器
  • 特定于一个项目的工具

添加本地范围服务器#

bash
复制
# 默认添加（本地范围）claude mcp add --transport http stripe https://mcp.stripe.com

# 显式指定本地范围claude mcp add --transport http stripe --scope local https://mcp.stripe.com

存储位置#

本地范围的服务器配置存储在：

json
复制
~/.claude/projects//mcp.json

特点#

  • 私密性: 仅对您可用
  • 项目特定: 仅在当前项目中工作
  • 不共享: 不会与其他开发者共享
  • 优先级: 最高优先级

项目范围#

概述#

项目范围的服务器通过在项目根目录中存储配置到 .mcp.json 文件来启用团队协作。此文件设计为检入版本控制，确保所有团队成员都可以访问相同的 MCP 工具和服务。

适用场景#

  • 团队共享服务器
  • 项目特定工具
  • 协作所需的服务
  • 标准化开发环境

添加项目范围服务器#

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

bash
复制
### 配置文件格式

生成的 `.mcp.json` 文件遵循标准化格式：

~~~json
```json

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

```### HTTP 服务器配置

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

stdio 服务器配置#

json
复制
```json

{
  "mcpServers": {
    "database-tools": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "DB_URL": "${DB_URL:-postgresql://localhost/db}"
      }
    }
  }
}

```### 环境变量扩展

Claude Code 支持 `.mcp.json` 文件中的环境变量扩展：

> **支持的语法**:
> - `${VAR}` - 扩展为环境变量 `VAR` 的值
> - `${VAR:-default}` - 如果设置了 `VAR`，则扩展为 `VAR`，否则使用 `default`

> **扩展位置**:
> - `command` - 服务器可执行文件路径
> - `args` - 命令行参数
> - `env` - 传递给服务器的环境变量
> - `url` - 对于 HTTP 服务器类型
> - `headers` - 对于 HTTP 服务器身份验证

> **示例**:

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

```
### 安全提示

出于安全原因，Claude Code 在使用来自 `.mcp.json` 文件的项目范围服务器之前会提示批准。

### 重置批准选择

如果需要重置这些批准选择：

~~~bash
```bash

claude mcp reset-project-choices

```## 用户范围

### 概述

用户范围的服务器提供跨项目可访问性，使其在您计算机上的所有项目中可用，同时对您的用户帐户保持私密。

### 适用场景

> - 个人实用程序服务器
> - 开发工具
> - 在不同项目中经常使用的服务
> - 个人工作流自动化

### 添加用户范围服务器

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

```
### 存储位置

用户范围的服务器配置存储在：

```> ~/.claude/mcp.json

特点#

  • 跨项目: 在所有项目中可用
  • 用户特定: 仅对您的用户帐户可用
  • 持久化: 配置持久保存
  • 优先级: 最低优先级

范围层次结构和优先级#

优先级顺序#

MCP 服务器配置遵循明确的优先级层次结构：

冲突解决#

当具有相同名称的服务器存在于多个范围时，系统按优先级解决冲突：

用户范围

claude mcp add --transport http github --scope user https://api.github.com/mcp

项目范围

claude mcp add --transport http github --scope project https://api.github.com/mcp

本地范围

claude mcp add --transport http github --scope local https://api.github.com/mcp

使用时，本地范围的 github 服务器将被使用

bash
复制
### 查看有效配置

bash

查看所有已配置的服务器

claude mcp list

查看特定服务器的详细信息

claude mcp get github

选择正确的范围#

决策树#

需要与团队共享？ 是 → 项目范围 否 → 需要在多个项目中使用？ 是 → 用户范围 否 → 本地范围

bash
复制
### 场景示例
#### 场景 1: 个人实验
~~~bash
bash

# 本地范围
claude mcp add --transport http experimental https://api.example.com/experimental

```#### 场景 2: 团队数据库

# 项目范围
claude mcp add --transport stdio db --scope project \
--env DB_URL=${DB_URL} \
-- npx -y @bytebase/dbhub

```
#### 场景 3: 个人工具

~~~bash
```bash

# 用户范围
claude mcp add --transport stdio formatter --scope user \
  -- npx -y @my/formatter

```## 最佳实践

### 1. 敏感凭证使用本地范围

# 包含 API 密钥的配置
claude mcp add --transport http private-api --scope local \
https://api.example.com/mcp \
--header "Authorization: Bearer your-secret-key"

```
### 2. 团队共享使用项目范围

~~~bash
```bash

# 团队共享的数据库配置
claude mcp add --transport stdio team-db --scope project \

--env DB_URL=${TEAM_DB_URL}
-- npx -y @bytebase/dbhub

bash
复制
# 个人开发工具
claude mcp add --transport stdio my-tools --scope user \
-- npx -y @my/tools

4. 使用环境变量#

json
复制
```json

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

```## 迁移配置

### 从本地迁移到项目

# 1. 查看本地配置
claude mcp get my-server
# 2. 添加到项目范围
claude mcp add --transport http my-server --scope project 
# 3. 删除本地配置
claude mcp remove my-server

```
### 从用户迁移到项目

~~~bash
```bash

# 1. 查看用户配置
claude mcp get my-server

# 2. 添加到项目范围
claude mcp add --transport http my-server --scope project 

# 3. 删除用户配置
claude mcp remove my-server

```

## 故障排除

### 配置未生效

**问题**: 配置更改未生效

**解决方案**:
1. 重启 Claude Code
2. 检查配置文件语法
3. 验证环境变量
4. 查看错误日志

### 环境变量未扩展

**问题**: 环境变量未正确扩展

**解决方案**:
1. 验证环境变量语法
2. 确认环境变量已设置
3. 检查默认值设置
4. 查看配置文件

### 权限问题

**问题**: 无法访问项目范围服务器

**解决方案**:
1. 检查文件权限
2. 验证 `.mcp.json` 存在
3. 确认项目目录正确
4. 重置批准选择
```
```