---
name: mcp-setup
description: 为增强代理能力配置常用的 MCP 服务器
level: 2
---

# MCP 设置

配置 Model Context Protocol（MCP）服务器，通过网页搜索、文件系统访问和 GitHub 集成等外部工具扩展 Claude Code 的能力。

## 概览

MCP 服务器会提供 Claude Code 代理可用的额外工具。此技能帮助你使用 `claude mcp add` 命令行接口配置常用的 MCP 服务器。

## 步骤 1：展示可用的 MCP 服务器

使用 AskUserQuestion 向用户展示可用的 MCP 服务器选项：

**问题：** "Which MCP server would you like to configure?"

**选项：**
1. **Context7** - 来自常用库的文档和代码上下文
2. **Exa Web Search** - 增强的网页搜索（替代内置 `websearch`）
3. **Filesystem** - 具有额外能力的扩展文件系统访问
4. **GitHub** - 用于 issue、PR 和仓库管理的 GitHub API 集成
5. **All of the above** - 配置所有推荐的 MCP 服务器
6. **Custom** - 添加自定义 MCP 服务器

## 步骤 2：收集所需信息

### 对于 Context7：
不需要 API key。可立即使用。

### 对于 Exa Web Search：
询问 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
```

### 对于 Filesystem：
询问允许访问的目录：
```
Which directories should the filesystem MCP have access to?
Default: Current working directory
Enter comma-separated paths, or press Enter for default
```

### 对于 GitHub：
询问 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
```

## 步骤 3：使用 CLI 添加 MCP 服务器

使用 `claude mcp add` 命令配置每个 MCP 服务器。CLI 会自动处理 `settings.json` 的更新与合并。

### Context7 配置：
```bash
claude mcp add context7 -- npx -y @upstash/context7-mcp
```

### Exa Web Search 配置：
```bash
claude mcp add -e EXA_API_KEY=<user-provided-key> exa -- npx -y exa-mcp-server
```

### Filesystem 配置：
```bash
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem <allowed-directories>
```

### GitHub 配置：

**选项 1：Docker（本地）**
```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
```

**选项 2：HTTP（远程）**
```bash
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
```

> 注意：Docker 选项要求已安装 Docker。HTTP 选项更简单，但能力可能有所不同。

## 步骤 4：验证安装

配置完成后，验证 MCP 服务器是否已正确设置：

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

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

## 步骤 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:omc-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 服务器

如果用户选择 "Custom"：

询问以下内容：
1. 服务器名称（标识符）
2. 传输类型：`stdio`（默认）或 `http`
3. 对于 stdio：命令和参数（例如，`npx my-mcp-server`）
4. 对于 http：URL（例如，`https://example.com/mcp`）
5. 环境变量（可选，`key=value` 对）
6. HTTP headers（可选，仅用于 `http` 传输）

然后构造并运行相应的 `claude mcp add` 命令：

**对于 stdio 服务器：**
```bash
# 不带环境变量
claude mcp add <server-name> -- <command> [args...]

# 带环境变量
claude mcp add -e KEY1=value1 -e KEY2=value2 <server-name> -- <command> [args...]
```

**对于 HTTP 服务器：**
```bash
# 基础 HTTP 服务器
claude mcp add --transport http <server-name> <url>

# 带 headers 的 HTTP 服务器
claude mcp add --transport http --header "Authorization: Bearer <token>" <server-name> <url>
```

## 常见问题

### MCP 服务器未加载
- 确保已安装 Node.js 18+
- 检查 `npx` 是否在 PATH 中可用
- 运行 `claude mcp list` 验证服务器状态
- 检查服务器日志中的错误

### API Key 问题
- Exa：在 https://dashboard.exa.ai 验证 key
- GitHub：确保 token 具有所需的 scopes（`repo`, `read:org`）
- 如有需要，使用正确的凭据重新运行 `claude mcp add`

### 代理仍在使用内置工具
- 配置后重启 Claude Code
- 配置 exa 后，内置 `websearch` 的优先级会降低
- 运行 `claude mcp list` 确认服务器处于激活状态

### 删除或更新服务器
- 删除：`claude mcp remove <server-name>`
- 更新：删除旧服务器，然后使用新配置重新添加