Claude Code 教程

简体中文

繁體中文
English

简体中文

繁體中文
English

主题

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
    {
      "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
    {
      "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. 添加到项目范围
```bash
    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. 重置批准选择

基于 MIT 许可发布

Copyright © 2024-present