MCP 安装范围

概述

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，用于团队共享。

适用场景

团队共享服务器
项目标准工具
统一开发环境

添加项目范围服务器

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

配置文件格式

{
  "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 服务器配置示例

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

环境变量扩展

支持以下语法：

${VAR}：扩展为环境变量值
${VAR:-default}：未设置则使用默认值

支持位置：

command
args
env
url
headers

示例：

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

安全提示

项目范围服务器使用前会提示批准。

重置批准选择

claude mcp reset-project-choices

用户范围

概述

用户范围服务器在所有项目中可用，但仅对当前用户有效。

适用场景

个人实用服务器
跨项目工具
个人工作流

添加用户范围服务器

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

存储位置

~/.claude/mcp.json

特点

跨项目可用
用户私有
持久保存
优先级最低

范围优先级

冲突时按以下优先级生效：

本地范围
项目范围
用户范围

# 用户范围
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

# 使用时本地范围优先生效

查看有效配置

# 查看所有已配置的服务器
claude mcp list

# 查看特定服务器详情
claude mcp get github

选择正确的范围

决策树

需要团队共享？→ 项目范围
需要跨项目使用？→ 用户范围
仅当前项目且敏感？→ 本地范围

场景示例

# 场景 1: 个人实验
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: 个人工具
claude mcp add --transport stdio formatter --scope user \
  -- npx -y @my/formatter

最佳实践

1. 敏感凭证用本地范围

claude mcp add --transport http private-api --scope local \
  https://api.example.com/mcp \
  --header "Authorization: Bearer your-secret-key"

2. 团队共享用项目范围

claude mcp add --transport stdio team-db --scope project \
  --env DB_URL=${TEAM_DB_URL} \
  -- npx -y @bytebase/dbhub

3. 使用环境变量

{
  "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

从用户迁移到项目

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

故障排除

配置未生效

重启 Claude Code
检查配置文件语法
验证环境变量
查看错误日志

环境变量未扩展

验证语法 ${VAR} 或 ${VAR:-default}
确认环境变量已设置
检查默认值设置

权限问题

检查文件权限
验证 .mcp.json 存在
确认项目目录正确
重置批准选择

MCP 安装范围

On this page