连接 MCP 服务器
一句话
为 Claude Code 添加 MCP 服务器,验证连接,并在磁盘上找到配置文件。
什么时候翻这页
- 需要为 Claude Code 添加新的工具或服务扩展功能
- MCP 服务器连接失败需要排查问题
- 需要在团队中共享 MCP 服务器配置
- 想了解 MCP 服务器的配置文件位置和作用域
核心概念
- MCP (Model Context Protocol):模型上下文协议,让 Claude Code 能够使用内置工具集之外的工具
- MCP 服务器:提供额外工具的服务,可以是本地进程或托管服务,如搜索问题跟踪器、查询数据库或控制浏览器
- 作用域(scope):服务器的配置范围,分为三种:
local:仅当前项目可用,默认作用域project:项目级配置,可共享给团队成员user:用户级配置,在所有项目中可用
- 传输方式(transport):服务器连接方式,常见有:
http:通过 URL 连接的托管服务stdio:作为本地子进程运行的服务器
怎么做
添加和验证服务器
-
添加服务器
claude mcp add --transport http <name> <url><name>:自定义的服务器名称<url>:服务器托管地址
-
检查连接状态
claude mcp list状态指示含义:
✓ Connected:已连接,可使用! Needs authentication:需要认证✗ Failed to connect:服务器未响应✗ Connection error:连接错误⏸ Pending approval:等待项目级服务器批准
-
使用服务器 在 Claude 会话中指定服务器名称:
Use the <name> server to [执行任务] -
移除服务器
claude mcp remove <name>
添加不同类型的服务器
-
本地服务器
claude mcp add <name> -- <command>- 使用
--分隔符,后面是要执行的命令
- 使用
-
需要认证的服务器
- 添加服务器后,使用
/mcp命令 - 选择服务器并选择
Authenticate - 在浏览器中完成认证
- 添加服务器后,使用
直接编辑配置文件
在项目根目录创建 .mcp.json:
{
"mcpServers": {
"<name>": {
"type": "http",
"url": "<url>"
}
}
}
命令 / 配置速查
| 命令/配置 | 说明 |
|---|---|
claude mcp add --transport http <name> <url> | 添加 HTTP 服务器 |
claude mcp add <name> -- <command> | 添加本地 stdio 服务器 |
claude mcp list | 列出服务器及其状态 |
claude mcp remove <name> | 移除服务器 |
claude mcp get <name> | 查看服务器配置详情 |
.mcp.json | 项目级配置文件 |
~/.claude.json | 用户级配置文件 |
MCP_TIMEOUT | 环境变量,设置服务器启动超时时间(毫秒) |
初学者易错点
- 在
claude会话内运行claude mcp add命令(应在会话外运行) - 添加本地服务器时忘记使用
--分隔符 - 混淆不同作用域(local、project、user)的适用场景
- 修改
.mcp.json后未重启 Claude Code 会话 - 忽略服务器认证需求导致连接失败
相关词条
mcp:MCP 协议概述managed-mcp:组织级 MCP 管理mcp-resources:MCP 资源引用mcp-prompts:MCP 提示命令env-vars:环境变量配置