Back to Details

mcp-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MCP Setup

MCP 配置

Configure Model Context Protocol (MCP) servers to extend Claude Code's capabilities with external tools like web search, file system access, and GitHub integration.
配置模型上下文协议（MCP）服务器，为Claude Code扩展网页搜索、文件系统访问、GitHub集成等外部工具能力。

Overview

概述

MCP servers provide additional tools that Claude Code agents can use. This skill helps you configure popular MCP servers using the 
claude mcp add
command-line interface.
MCP服务器可为Claude Code Agent提供额外工具。本指南将帮助你通过
claude mcp add
命令行界面配置主流MCP服务器。

Step 1: Show Available MCP Servers

步骤1：查看可用的MCP服务器

Present the user with available MCP server options using AskUserQuestion:
Question: "Which MCP server would you like to configure?"
Options:
  1. Context7 - Documentation and code context from popular libraries
  2. Exa Web Search - Enhanced web search (replaces built-in websearch)
  3. Filesystem - Extended file system access with additional capabilities
  4. GitHub - GitHub API integration for issues, PRs, and repository management
  5. All of the above - Configure all recommended MCP servers
  6. Custom - Add a custom MCP server
通过询问用户问题展示可选的MCP服务器：
问题： "你想要配置哪款MCP服务器？"
选项：
  1. Context7 - 主流库的文档与代码上下文查询
  2. Exa Web Search - 增强型网页搜索（替代内置网页搜索功能）
  3. Filesystem - 扩展文件系统访问能力
  4. GitHub - GitHub API集成，支持议题、PR与仓库管理
  5. 以上全部 - 配置所有推荐的MCP服务器
  6. 自定义 - 添加自定义MCP服务器

Step 2: Gather Required Information

步骤2：收集必要信息

For Context7:

针对Context7：

No API key required. Ready to use immediately.
无需API密钥，可直接使用。

For Exa Web Search:

针对Exa Web Search：

Ask for API key:
Do you have an Exa API key?
- Get one at: https://exa.ai
- Enter your API key, or type 'skip' to configure later
询问API密钥：
你是否拥有Exa API密钥？
- 获取地址：https://exa.ai
- 输入你的API密钥，或输入'skip'稍后配置

For Filesystem:

针对Filesystem：

Ask for allowed directories:
Which directories should the filesystem MCP have access to?
Default: Current working directory
Enter comma-separated paths, or press Enter for default
询问允许访问的目录：
文件系统MCP需要访问哪些目录？
默认：当前工作目录
输入逗号分隔的路径，或按回车键使用默认设置

For GitHub:

针对GitHub：

Ask for token:
Do you have a GitHub Personal Access Token?
- Create one at: https://github.com/settings/tokens
- Recommended scopes: repo, read:org
- Enter your token, or type 'skip' to configure later
询问令牌：
你是否拥有GitHub个人访问令牌？
- 创建地址：https://github.com/settings/tokens
- 推荐权限范围：repo, read:org
- 输入你的令牌，或输入'skip'稍后配置

Step 3: Add MCP Servers Using CLI

步骤3：通过CLI添加MCP服务器

Use the 
claude mcp add
command to configure each MCP server. The CLI automatically handles settings.json updates and merging.
使用
claude mcp add
命令配置各MCP服务器，CLI会自动处理settings.json的更新与合并。

Context7 Configuration:

Context7配置：

bash
claude mcp add context7 -- npx -y @upstash/context7-mcp
bash
claude mcp add context7 -- npx -y @upstash/context7-mcp

Exa Web Search Configuration:

Exa Web Search配置：

bash
claude mcp add -e EXA_API_KEY=<user-provided-key> exa -- npx -y exa-mcp-server
bash
claude mcp add -e EXA_API_KEY=<用户提供的密钥> exa -- npx -y exa-mcp-server

Filesystem Configuration:

Filesystem配置：

bash
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem <allowed-directories>
bash
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem <允许访问的目录>

GitHub Configuration:

GitHub配置：

Option 1: Docker (local)
bash
claude mcp add -e GITHUB_PERSONAL_ACCESS_TOKEN=<user-provided-token> github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
Option 2: HTTP (remote)
bash
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
Note: Docker option requires Docker installed. HTTP option is simpler but may have different capabilities.
选项1：Docker（本地）
bash
claude mcp add -e GITHUB_PERSONAL_ACCESS_TOKEN=<用户提供的令牌> github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
选项2：HTTP（远程）
bash
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
注意：Docker选项需要已安装Docker。HTTP选项操作更简单，但功能可能有所不同。

Step 4: Verify Installation

步骤4：验证安装

After configuration, verify the MCP servers are properly set up:
bash
undefined
配置完成后，验证MCP服务器是否正常设置：
bash
undefined

List configured MCP servers

列出已配置的MCP服务器

claude mcp list

This will display all configured MCP servers and their status.
claude mcp list

该命令将显示所有已配置的MCP服务器及其状态。

Step 5: Show Completion Message

步骤5：显示完成消息

MCP Server Configuration Complete!

CONFIGURED SERVERS:
[List the servers that were configured]

NEXT STEPS:
1. Restart Claude Code for changes to take effect
2. The configured MCP tools will be available to all agents
3. Run `claude mcp list` to verify configuration

USAGE TIPS:
- Context7: Ask about library documentation (e.g., "How do I use React hooks?")
- Exa: Use for web searches (e.g., "Search the web for latest TypeScript features")
- Filesystem: Extended file operations beyond the working directory
- GitHub: Interact with GitHub repos, issues, and PRs

TROUBLESHOOTING:
- If MCP servers don't appear, run `claude mcp list` to check status
- Ensure you have Node.js 18+ installed for npx-based servers
- For GitHub Docker option, ensure Docker is installed and running
- Run /oh-my-claudecode:doctor to diagnose issues

MANAGING MCP SERVERS:
- Add more servers: /oh-my-claudecode:mcp-setup or `claude mcp add ...`
- List servers: `claude mcp list`
- Remove a server: `claude mcp remove <server-name>`
MCP服务器配置完成！

已配置的服务器：
[列出已配置的服务器]

下一步：
1. 重启Claude Code使更改生效
2. 已配置的MCP工具将对所有Agent可用
3. 运行`claude mcp list`验证配置

使用提示：
- Context7：查询库文档（例如："如何使用React hooks？"）
- Exa：用于网页搜索（例如："搜索最新TypeScript特性"）
- Filesystem：实现工作目录之外的扩展文件操作
- GitHub：与GitHub仓库、议题和PR交互

故障排除：
- 如果MCP服务器未显示，运行`claude mcp list`检查状态
- 确保已安装Node.js 18+以支持基于npx的服务器
- 对于GitHub Docker选项，确保Docker已安装并运行
- 运行/oh-my-claudecode:doctor诊断问题

管理MCP服务器：
- 添加更多服务器：/oh-my-claudecode:mcp-setup 或 `claude mcp add ...`
- 列出服务器：`claude mcp list`
- 删除服务器：`claude mcp remove <服务器名称>`

Custom MCP Server

自定义MCP服务器

If user selects "Custom":
Ask for:
  1. Server name (identifier)
  2. Transport type: 
    stdio
    (default) or 
    http
  3. For stdio: Command and arguments (e.g., 
    npx my-mcp-server
    )
  4. For http: URL (e.g., 
    https://example.com/mcp
    )
  5. Environment variables (optional, key=value pairs)
  6. HTTP headers (optional, for http transport only)
Then construct and run the appropriate 
claude mcp add
command:
For stdio servers:
bash
undefined
如果用户选择“自定义”：
询问以下信息：
  1. 服务器名称（标识符）
  2. 传输类型：
    stdio
    （默认）或
    http
  3. 对于stdio：命令与参数（例如：
    npx my-mcp-server
    ）
  4. 对于http：URL（例如：
    https://example.com/mcp
    ）
  5. 环境变量（可选，键=值对）
  6. HTTP头（可选，仅适用于http传输）
然后构造并运行对应的
claude mcp add
命令：
针对stdio服务器：
bash
undefined

Without environment variables

无环境变量

claude mcp add <server-name> -- <command> [args...]
claude mcp add <服务器名称> -- <命令> [参数...]

With environment variables

带环境变量

claude mcp add -e KEY1=value1 -e KEY2=value2 <server-name> -- <command> [args...]

**For HTTP servers:**
```bash
claude mcp add -e KEY1=value1 -e KEY2=value2 <服务器名称> -- <命令> [参数...]

**针对HTTP服务器：**
```bash

Basic HTTP server

基础HTTP服务器

claude mcp add --transport http <server-name> <url>
claude mcp add --transport http <服务器名称> <URL>

HTTP server with headers

带HTTP头的服务器

claude mcp add --transport http --header "Authorization: Bearer <token>" <server-name> <url>
undefined
claude mcp add --transport http --header "Authorization: Bearer <令牌>" <服务器名称> <URL>
undefined

Common Issues

常见问题

MCP Server Not Loading

MCP服务器无法加载

  • Ensure Node.js 18+ is installed
  • Check that npx is available in PATH
  • Run 
    claude mcp list
    to verify server status
  • Check server logs for errors
  • 确保已安装Node.js 18+
  • 检查npx是否在PATH中可用
  • 运行
    claude mcp list
    验证服务器状态
  • 查看服务器日志排查错误

API Key Issues

API密钥问题

  • Exa: Verify key at https://dashboard.exa.ai
  • GitHub: Ensure token has required scopes (repo, read:org)
  • Re-run 
    claude mcp add
    with correct credentials if needed

Agents Still Using Built-in Tools

Agent仍使用内置工具

  • Restart Claude Code after configuration
  • The built-in websearch will be deprioritized when exa is configured
  • Run 
    claude mcp list
    to confirm servers are active
  • 配置完成后重启Claude Code
  • 配置Exa后，内置网页搜索功能会被优先降级
  • 运行
    claude mcp list
    确认服务器处于活跃状态

Removing or Updating a Server

删除或更新服务器

  • Remove: 
    claude mcp remove <server-name>
  • Update: Remove the old server, then add it again with new configuration
  • 删除：
    claude mcp remove <服务器名称>
  • 更新：先删除旧服务器，再重新添加新配置的服务器