12.2 MCP 安装范围

约 1290 字大约 4 分钟

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

本地范围

概述

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

适用场景

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

添加本地范围服务器

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

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

存储位置

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

~/.claude/projects/<project-id>/mcp.json

特点

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

项目范围

概述

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

适用场景

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

添加项目范围服务器

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

### 配置文件格式

生成的 `.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 服务器将被使用

查看所有已配置的服务器

claude mcp list

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

claude mcp get github

选择正确的范围#

决策树#

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

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

4. 使用环境变量#

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

# 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. 重置批准选择
```
```
```