Claude Code 使用指南

主题

MCP 配置 ​

Configuring and Managing MCP Servers in Claude Code

Claude Code 提供了多种方式来配置 MCP 服务器，从命令行快速添加到配置文件精细管理，满足个人开发和团队协作的不同需求。本章将详细介绍每种配置方式的用法、适用场景，以及常见问题的排查方法。

配置方式一：claude mcp add 命令 ​

Method 1: The claude mcp add Command (Recommended)

使用命令行是配置 MCP 服务器最快捷的方式，推荐在日常开发中使用。

基本语法 ​

bash
claude mcp add [options] <name> [-- <command> [args...]]

其中：

  • <name>：为 MCP 服务器指定一个名称（自定义，便于管理）
  • <command>：启动 MCP 服务器的命令
  • [args...]：传递给服务器的参数

添加 stdio 类型服务器 ​

Adding stdio Transport Servers

stdio 是最常用的传输类型，服务器作为本地子进程运行：

bash
# 添加一个 Node.js 实现的 MCP 服务器
claude mcp add my-filesystem -- node /path/to/filesystem-server.js /allowed/directory

# 使用 npx 直接运行（无需预先安装）
claude mcp add github-server -- npx -y @anthropic/github-mcp-server

# 添加 Python 实现的 MCP 服务器
claude mcp add my-python-tool -- python3 /path/to/server.py

# 使用 uvx 运行 Python MCP 服务器
claude mcp add db-server -- uvx mcp-server-postgres postgresql://localhost/mydb

添加 SSE 类型服务器 ​

Adding SSE Transport Servers

连接远程 SSE（Server-Sent Events）MCP 服务器：

bash
# 使用 --transport 指定传输类型
claude mcp add --transport sse my-remote-server https://mcp.example.com/sse

# 带有认证头的远程服务器
claude mcp add --transport sse auth-server https://mcp.example.com/sse \
  --header "Authorization: Bearer YOUR_TOKEN"

添加 Streamable HTTP 类型服务器 ​

Adding Streamable HTTP Transport Servers

连接使用最新 Streamable HTTP 协议的服务器：

bash
# 使用 http 传输类型
claude mcp add --transport http cloud-server https://mcp.example.com/mcp

作用域选项 ​

Scope Options

-s 或 --scope 参数控制配置的作用域，决定了 MCP 服务器的可见范围：

bash
# 用户级（默认）—— 在所有项目中可用
claude mcp add -s user my-tool -- node /path/to/tool.js

# 项目级 —— 仅在当前项目中可用
claude mcp add -s project my-tool -- node /path/to/tool.js
作用域存储位置适用场景
user~/.claude/settings.json通用工具，如搜索引擎、浏览器
project.mcp.json（项目根目录）项目专用工具，如数据库连接

传递环境变量 ​

Passing Environment Variables

使用 -e 参数传递环境变量给 MCP 服务器：

bash
# 传递 API 密钥
claude mcp add -e API_KEY=your-key-here my-server -- node server.js

# 传递多个环境变量
claude mcp add \
  -e GITHUB_TOKEN=ghp_xxxxx \
  -e GITHUB_ORG=my-org \
  github-server -- npx -y @anthropic/github-mcp-server

# 引用系统环境变量
claude mcp add -e API_KEY=$MY_API_KEY my-server -- node server.js

完整示例 ​

Complete Examples

以下是几个常见 MCP 服务器的配置命令：

bash
# Exa 搜索引擎
claude mcp add -e EXA_API_KEY=your-exa-key exa-search -- \
  npx -y exa-mcp-server

# Figma 设计稿
claude mcp add -e FIGMA_API_KEY=your-figma-key figma -- \
  npx -y @anthropic/framelink-figma-mcp

# PostgreSQL 数据库
claude mcp add postgres -- \
  npx -y @anthropic/mcp-server-postgres \
  postgresql://user:pass@localhost:5432/mydb

# 文件系统访问
claude mcp add filesystem -- \
  npx -y @anthropic/mcp-server-filesystem \
  /home/user/projects /home/user/documents

# Puppeteer 浏览器
claude mcp add puppeteer -- npx -y @anthropic/mcp-server-puppeteer

# Sentry 错误监控
claude mcp add -e SENTRY_AUTH_TOKEN=your-token sentry -- \
  npx -y @anthropic/mcp-server-sentry

配置方式二：.mcp.json 文件 ​

Method 2: The .mcp.json Configuration File

对于团队项目，使用 .mcp.json 文件是最佳实践。将该文件放在项目根目录并纳入版本控制，团队成员就能共享相同的 MCP 配置。

文件格式 ​

File Format

json
{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

完整示例 ​

Full Example

json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/github-mcp-server"],
      "env": {
        "GITHUB_TOKEN": ""
      }
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-server-postgres",
        "postgresql://localhost:5432/devdb"
      ]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-server-filesystem",
        "./src",
        "./docs"
      ]
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": ""
      }
    }
  }
}

环境变量处理策略 ​

Environment Variable Handling

在 .mcp.json 中，敏感信息（如 API 密钥）不应该直接写入文件。推荐的处理方式：

方式 A：留空，由各开发者在本地设置

json
{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": ""
      }
    }
  }
}

当 env 中的值为空字符串时，Claude Code 会尝试从系统环境变量中读取同名变量。开发者只需在自己的 shell 配置文件中设置：

bash
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export EXA_API_KEY="your-actual-key"

方式 B：使用环境变量引用

json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

项目共享注意事项 ​

Notes on Sharing with Team

project-root/
├── .mcp.json          ← MCP 配置（提交到 Git）
├── .env               ← 环境变量（加入 .gitignore）
├── .gitignore
├── src/
└── ...

在 .gitignore 中确保敏感信息不会被提交：

gitignore
# 环境变量文件
.env
.env.local
.env.*.local

配置方式三：settings.json 中的 mcpServers 字段 ​

Method 3: The mcpServers Field in settings.json

Claude Code 的用户设置文件也可以用来配置全局 MCP 服务器。

用户级设置 ​

User-Level Settings

文件位置：~/.claude/settings.json

json
{
  "mcpServers": {
    "exa-search": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your-key"
      }
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-puppeteer"]
    }
  }
}

项目级设置 ​

Project-Level Settings

文件位置：<project-root>/.claude/settings.json

json
{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-server-postgres",
        "postgresql://localhost:5432/project_dev"
      ]
    }
  }
}

三种配置方式对比 ​

Comparison of Three Configuration Methods

特性claude mcp add.mcp.jsonsettings.json
操作方式命令行编辑文件编辑文件
适合场景快速添加团队共享持久化配置
版本控制不适合推荐不推荐
作用域user/projectprojectuser/project
团队协作个人使用团队共享个人使用
灵活性高中中

优先级规则 ​

Priority Rules

当同名 MCP 服务器在多处配置时，优先级从高到低为：

  1. 项目级 .mcp.json
  2. 项目级 .claude/settings.json
  3. 用户级 ~/.claude/settings.json
  4. claude mcp add 命令添加的配置（根据 scope 存入对应文件）

管理已配置的 MCP 服务器 ​

Managing Configured MCP Servers

查看服务器列表 ​

Listing Servers

bash
# 列出所有已配置的 MCP 服务器
claude mcp list

# 示例输出
# ┌─────────────┬───────┬─────────────────────────────────┐
# │ Name        │ Type  │ Command                         │
# ├─────────────┼───────┼─────────────────────────────────┤
# │ exa-search  │ stdio │ npx -y exa-mcp-server          │
# │ github      │ stdio │ npx -y @anthropic/github-mcp   │
# │ remote-api  │ sse   │ https://mcp.example.com/sse    │
# └─────────────┴───────┴─────────────────────────────────┘

查看服务器详情 ​

Viewing Server Details

bash
# 查看特定服务器的详细配置
claude mcp get <name>

# 示例
claude mcp get exa-search

移除服务器 ​

Removing Servers

bash
# 移除指定的 MCP 服务器
claude mcp remove <name>

# 移除特定作用域的服务器
claude mcp remove -s project my-tool
claude mcp remove -s user my-tool

# 示例
claude mcp remove exa-search

环境变量详解 ​

Environment Variables in Detail

环境变量是 MCP 配置中的重要组成部分，尤其是在需要传递 API 密钥和认证信息时。

传递方式汇总 ​

Summary of Passing Methods

bash
# 方式 1：命令行 -e 参数
claude mcp add -e KEY=value server -- command

# 方式 2：.mcp.json 中的 env 字段
# { "env": { "KEY": "value" } }

# 方式 3：系统环境变量（自动继承）
export KEY=value
claude mcp add server -- command  # 服务器进程自动继承环境变量

常见环境变量 ​

Common Environment Variables

MCP 服务器环境变量说明
ExaEXA_API_KEYExa 搜索 API 密钥
GitHubGITHUB_TOKENGitHub Personal Access Token
FigmaFIGMA_API_KEYFigma API 访问密钥
SentrySENTRY_AUTH_TOKENSentry 认证令牌
SlackSLACK_BOT_TOKENSlack Bot 令牌
PostgreSQL连接字符串作为参数postgresql://user:pass@host/db

安全最佳实践 ​

Security Best Practices

bash
# 推荐：使用系统密钥管理工具
claude mcp add -e API_KEY=$(op read "op://Vault/Item/Field") server -- command

# 推荐：从 .env 文件加载（不提交到 Git）
source .env && claude mcp add -e API_KEY=$API_KEY server -- command

# 不推荐：直接在命令中写入密钥
claude mcp add -e API_KEY=sk-actual-secret-key server -- command

故障排查 ​

Troubleshooting

使用 claude mcp serve 调试 ​

Debugging with claude mcp serve

claude mcp serve 命令可以将 Claude Code 自身作为 MCP 服务器运行，这对于调试 MCP 通信非常有用：

bash
# 以 MCP 服务器模式启动 Claude Code
claude mcp serve

# 配合 MCP Inspector 使用
npx @anthropic/mcp-inspector

常见问题及解决方案 ​

Common Issues and Solutions

问题 1：MCP 服务器无法启动 ​

Error: Failed to start MCP server "my-server"

排查步骤：

bash
# 1. 检查命令是否可以直接运行
npx -y @anthropic/some-mcp-server

# 2. 检查 Node.js/Python 版本
node --version   # 建议 18+
python3 --version

# 3. 检查包是否存在
npm view @anthropic/some-mcp-server

# 4. 清除 npx 缓存后重试
npx --yes clear-npx-cache

问题 2：环境变量未生效 ​

Error: API key not found

排查步骤：

bash
# 1. 确认环境变量已设置
echo $EXA_API_KEY

# 2. 检查 MCP 配置中的 env 字段
claude mcp get exa-search

# 3. 尝试重新添加并显式传递
claude mcp remove exa-search
claude mcp add -e EXA_API_KEY=$EXA_API_KEY exa-search -- npx -y exa-mcp-server

问题 3：SSE 连接超时 ​

Error: SSE connection timed out

排查步骤：

bash
# 1. 检查网络连接
curl -I https://mcp.example.com/sse

# 2. 检查是否需要代理
export HTTPS_PROXY=http://proxy:port

# 3. 检查防火墙设置

问题 4：工具调用返回错误 ​

MCP tool error: Permission denied

排查步骤：

bash
# 1. 检查 MCP 服务器的权限设置
# 2. 确认文件系统路径可访问
# 3. 确认数据库连接信息正确
# 4. 查看 MCP 服务器日志输出

调试技巧 ​

Debugging Tips

bash
# 使用 MCP Inspector 可视化调试
npx @anthropic/mcp-inspector

# 在 Inspector 中可以：
# - 查看服务器能力列表
# - 手动调用工具并查看结果
# - 监控通信消息
# - 测试不同参数组合

日志位置 ​

Log Locations

平台日志路径
macOS~/Library/Logs/Claude/mcp*.log
Linux~/.local/share/claude/logs/mcp*.log
Windows%APPDATA%\Claude\logs\mcp*.log

高级配置 ​

Advanced Configuration

配置多个同类型服务器 ​

Configuring Multiple Servers of the Same Type

json
{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-postgres", "postgresql://localhost:5432/dev_db"]
    },
    "postgres-staging": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-postgres", "postgresql://staging-host:5432/staging_db"]
    }
  }
}

条件化配置 ​

Conditional Configuration

在不同环境中使用不同配置：

bash
# 开发环境
claude mcp add -s project dev-db -- npx -y @anthropic/mcp-server-postgres \
  postgresql://localhost:5432/dev_db

# 测试环境（通过不同名称区分）
claude mcp add -s project test-db -- npx -y @anthropic/mcp-server-postgres \
  postgresql://test-server:5432/test_db

小结 ​

Summary

Claude Code 提供了灵活且强大的 MCP 配置体系。对于个人使用，claude mcp add 命令是最快捷的方式；对于团队协作，.mcp.json 文件能确保配置一致性。无论选择哪种方式，合理管理环境变量和定期检查服务器状态都是保持 MCP 稳定运行的关键。

下一步：阅读 热门 MCP 服务 了解有哪些 MCP 服务器值得使用。