文档 / 使用指南 / MCP 服务器配置

MCP 服务器配置

连接外部工具和数据源，扩展 Claude Code 能力边界

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 命令添加服务器：

# 添加文件系统服务器
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 文件：

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

常用 MCP 服务器

文件系统

访问本地文件系统：

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

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

SQLite 数据库

连接 SQLite 数据库：

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

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

GitHub

连接 GitHub 仓库：

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

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

Context7（文档检索）

获取最新的库文档：

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

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

Supabase

连接 Supabase 后端：

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

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

Playwright（浏览器自动化）

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

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

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

Tavily（网络搜索）

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

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

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

Docker

容器管理：

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

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

服务器类型

stdio（本地进程）

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

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

特点：

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

  • Claude Code 管理进程生命周期

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

SSE（服务器推送事件）

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

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

特点：

  • 适合云端服务

  • 支持 OAuth 认证

  • 无需本地安装

HTTP

RESTful API 方式：

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

环境变量

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

{
  "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：数据库查询助手

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

使用：

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

示例 2：Kubernetes 运维

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

使用：

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

示例 3：多服务器配置

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

下一步

← 上一篇
CI/CD 集成
下一篇 →
插件开发