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. 重置批准選擇

```

```