# MCP 服务器

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 推出的开放标准，允许 Claude Code 连接外部工具、数据库、API 和服务。通过 MCP，你可以大幅扩展 Claude Code 的能力。

## 什么是 MCP？

### 基本概念

MCP 是一个**开放协议**，定义了 AI 助手与外部系统之间的通信标准。它包含三个核心组件：

| 组件 | 说明 | 示例 |
|------|------|------|
| **Tools（工具）** | 可执行的操作 | 查询数据库、发送请求、操作文件 |
| **Resources（资源）** | 可读取的数据 | 文件内容、API 响应、数据库记录 |
| **Prompts（提示）** | 预定义的任务模板 | 代码审查模板、报告生成模板 |

### 为什么需要 MCP？

- **扩展能力**：让 Claude 访问它原本无法访问的系统

- **实时数据**：获取最新的文档、数据库内容、API 数据

- **自动化操作**：执行部署、发送通知、管理资源

- **保持隐私**：数据在本地处理，不需要上传到云端

## 快速开始

### 查看 MCP 状态

```
> /mcp
```

显示当前已配置的 MCP 服务器状态。

### 添加 MCP 服务器

使用 `claude mcp add` 命令添加服务器：

```bash
# 添加文件系统服务器
claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/directory

# 添加 SQLite 数据库服务器
claude mcp add sqlite npx -y mcp-server-sqlite ./database.db

# 添加自定义服务器
claude mcp add my-server node /path/to/server.js
```

### 配置文件方式

也可以在项目根目录创建 `.mcp.json` 文件：

```json
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
  },
  "database": {
    "command": "npx",
    "args": ["-y", "mcp-server-sqlite", "./data.db"]
  }
}
```

## 常用 MCP 服务器

### 文件系统

访问本地文件系统：

```json
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
  }
}
```

**功能**：读取、写入、搜索指定目录中的文件。

### SQLite 数据库

连接 SQLite 数据库：

```json
{
  "sqlite": {
    "command": "npx",
    "args": ["-y", "mcp-server-sqlite", "./database.db"]
  }
}
```

**功能**：执行 SQL 查询、管理数据库结构。

### GitHub

连接 GitHub 仓库：

```json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
```

**功能**：管理 Issues、PR、仓库操作。

### Context7（文档检索）

获取最新的库文档：

```json
{
  "context7": {
    "command": "npx",
    "args": ["-y", "@context7/mcp-server"]
  }
}
```

**功能**：获取任意库的最新文档和代码示例。

### Supabase

连接 Supabase 后端：

```json
{
  "supabase": {
    "command": "npx",
    "args": ["-y", "@supabase/mcp-server"],
    "env": {
      "SUPABASE_URL": "${SUPABASE_URL}",
      "SUPABASE_KEY": "${SUPABASE_KEY}"
    }
  }
}
```

**功能**：数据库操作、身份验证、存储管理。

### Playwright（浏览器自动化）

自动化浏览器操作和网页快照：

```json
{
  "playwright": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-playwright"]
  }
}
```

**功能**：网页截图、表单填写、页面导航、元素点击。

### Tavily（网络搜索）

为 Claude 提供实时网络搜索能力：

```json
{
  "tavily": {
    "command": "npx",
    "args": ["-y", "tavily-mcp-server"],
    "env": {
      "TAVILY_API_KEY": "${TAVILY_API_KEY}"
    }
  }
}
```

**功能**：网络搜索、网页内容提取、研究调查。

### Docker

容器管理：

```json
{
  "docker": {
    "command": "npx",
    "args": ["-y", "@docker/mcp-server"]
  }
}
```

**功能**：管理容器、镜像、网络。

## 服务器类型

### stdio（本地进程）

最常用的类型，作为本地子进程运行：

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

**特点**：

- 本地运行，数据不离开本机

- Claude Code 管理进程生命周期

- 适合文件系统、本地数据库等

### SSE（服务器推送事件）

> **⚠️ MCP 协议 2025-11-25 起 SSE 已弃用**：新连接推荐使用 **Streamable HTTP**（下方 HTTP 小节）。SSE 仅保留向后兼容存量服务器。


连接远程托管的 MCP 服务器：

```json
{
  "remote-server": {
    "type": "sse",
    "url": "https://mcp.example.com/sse"
  }
}
```

**特点**：

- 适合云端服务

- 支持 OAuth 认证

- 无需本地安装

### HTTP

RESTful API 方式：

```json
{
  "api-server": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}"
    }
  }
}
```

## 环境变量

MCP 配置支持环境变量替换：

```json
{
  "my-server": {
    "command": "node",
    "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL}",
      "API_KEY": "${API_KEY}",
      "DEFAULT_NAMESPACE": "${K8S_NAMESPACE:-default}"
    }
  }
}
```

**语法**：

- `${VAR}` - 替换为环境变量值

- `${VAR:-default}` - 如果变量未设置，使用默认值

## 实际应用示例

### 示例 1：数据库查询助手

```json
{
  "postgres": {
    "command": "npx",
    "args": ["-y", "mcp-server-postgres"],
    "env": {
      "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
    }
  }
}
```

使用：

```
> 查询最近 7 天的订单总金额
> 找出购买次数最多的前 10 个用户
```

### 示例 2：Kubernetes 运维

```json
{
  "kubernetes": {
    "command": "node",
    "args": ["./k8s-mcp-server.js"],
    "env": {
      "KUBECONFIG": "${KUBECONFIG}",
      "K8S_NAMESPACE": "${K8S_NAMESPACE:-default}"
    }
  }
}
```

使用：

```
> 列出所有 Pod 的状态
> 重启 api-server 部署
> 查看最近的错误日志
```

### 示例 3：多服务器配置

```json
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
  },
  "database": {
    "command": "npx",
    "args": ["-y", "mcp-server-sqlite", "./data.db"]
  },
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
```

## 故障排除

### 服务器无法启动

1. 检查命令是否正确安装：
   ```bash
   npx -y @modelcontextprotocol/server-filesystem --help
   ```

2. 检查环境变量是否设置：
   ```bash
   echo $GITHUB_TOKEN
   ```

3. 查看 Claude Code 日志获取错误信息

### 工具不可用

1. 使用 `/mcp` 检查服务器状态

2. 确认配置文件格式正确（JSON 语法）

3. 重启 Claude Code 重新加载配置

### 权限问题

- 确保文件路径有读写权限

- 数据库连接字符串正确

- API Token 有效且有足够权限

## 安全建议

1. **最小权限原则**：只授予必要的访问权限

2. **保护敏感信息**：使用环境变量存储 Token 和密码

3. **限制路径访问**：文件系统服务器只开放必要目录

4. **定期轮换密钥**：定期更新 API Token

## 安全须知

MCP 服务器以你的身份运行，可以读取数据、调用工具、访问凭证。引入第三方 MCP 服务器相当于把外部代码接入你的开发环境，需谨慎对待。

**主要风险**

- **数据外泄**：恶意或被攻破的服务器可能把你的代码、文件或对话内容回传到外部。

- **工具投毒（tool poisoning）**：服务器在工具描述中夹带隐藏指令，诱导 Claude 执行你未授权的操作。

- **凭证暴露**：配置不当的服务器可能读取到环境变量、密钥或令牌。

- **权限过大**：授予的工具能力超出实际所需，扩大了攻击面。

**关键防护**

- **只装可信服务器**：优先选择官方或经过审查、开源可审计的 MCP 服务器，避免来路不明的实现。

- **最小权限**：逐项审查每个服务器声明的工具范围，只开放真正需要的能力与目录。

- **保留人工审批关卡**：Claude Code 在执行工具调用前会请求确认，对删除、写入、涉及凭证等破坏性操作不要盲目放行或全量自动批准。

- **隔离凭证**：在沙箱中运行命令时使用 `sandbox.credentials` 阻止沙箱进程读取密钥与环境变量。

- **审计调用**：记录并定期检查工具调用日志，及时发现异常行为。

完整的威胁模型、沙箱与凭证隔离配置请参阅 [安全最佳实践](/docs/advanced/security)。

## 下一步

- 学习 [插件系统](/docs/advanced/plugins) 创建自定义功能

- 查看 [CLI 技巧](/docs/usage/cli-tips) 提升使用效率

- 探索 [工作流技巧](/docs/usage/workflow-tips) 优化开发流程