12.2 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/<project-id>/mcp.json

### 特点


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

## 项目范围

### 概述


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

### 适用场景

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

### 添加项目范围服务器

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

    bash


    ### 配置文件格式

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

    ~~~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

```### 3. 个人工具使用用户范围

# 个人开发工具

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 <url>
# 3. 删除本地配置
claude mcp remove my-server

```

### 从用户迁移到项目

~~~bash

```bash

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

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

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

```

## 故障排除

### 配置未生效

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

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

### 环境变量未扩展

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

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

### 权限问题

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

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

```

```