Claude Code MCP 安装与卸载指南

Claude Code 通过 MCP（Model Context Protocol）连接外部工具和数据源，让 Claude 能直接操作数据库、Issue 追踪器、浏览器等。本文详细介绍 MCP Server 的三种安装级别（local / project / user）、传输方式、以及卸载方法。

# 一、MCP 是什么

MCP（Model Context Protocol）是 Anthropic 推出的开源协议，用于 AI 与外部工具通信。Claude Code 作为 MCP 客户端，可以连接各种 MCP Server，从而获得额外的 tool 能力。

简单理解：

Claude Code（客户端） ←→ MCP Server（工具提供方） ←→ 外部服务（数据库/API/浏览器...）

常见用途：

连接 Jira / GitHub Issues 追踪任务
查询 PostgreSQL / MySQL 数据库
操作浏览器自动化
读取本地文件系统
调用自定义 API

# 二、三种安装级别（Scope）

Claude Code 的 MCP 配置分为三个级别，区别在于作用范围和配置文件位置：

级别	参数	作用范围	配置文件位置	适用场景
local	`--scope local`（默认）	仅当前项目，仅自己可用	`~/.claude.json` 项目条目下	个人开发测试
project	`--scope project`	当前项目，团队共享	项目根目录 `.mcp.json`	团队协作，提交到 Git
user	`--scope user`	所有项目，全局可用	`~/.claude.json` 全局条目下	常用工具，到处可用

# 2.1 local 级别（默认）

最常用的级别。MCP Server 仅在当前项目目录下生效，切换到其他项目不会加载。

# 基本语法
claude mcp add <name> -- <command> [args...]

# 示例：添加 markitdown（本地 stdio 服务）
claude mcp add markitdown -- python -m markitdown_mcp

# 示例：添加 filesystem 服务
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/blog

1
2
3
4
5
6
7
8

💡 不指定 --scope 时默认就是 local。

# 2.2 project 级别（团队共享）

写入项目根目录的 .mcp.json 文件，可以提交到 Git，团队成员 clone 后即可使用相同的 MCP 配置。

# 添加到项目级配置
claude mcp add --scope project markitdown -- python -m markitdown_mcp

# 添加带环境变量的服务
claude mcp add --scope project --env AIRTABLE_API_KEY=YOUR_KEY \
  --transport stdio airtable -- npx -y airtable-mcp-server

1
2
3
4
5
6

生成的 .mcp.json 文件内容示例：

{
  "mcpServers": {
    "markitdown": {
      "command": "python",
      "args": ["-m", "markitdown_mcp"]
    },
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "YOUR_KEY"
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

⚠️ 安全提示：如果 .mcp.json 包含 API Key 等敏感信息，不要直接提交到公开仓库。可以用环境变量引用，或将 .mcp.json 加入 .gitignore。

# 2.3 user 级别（全局可用）

对所有项目生效，适合安装通用工具（如 markitdown、filesystem 等）。

# 全局安装 markitdown
claude mcp add --scope user markitdown -- python -m markitdown_mcp

# 全局安装 context7（文档搜索服务，HTTP 传输）
claude mcp add --scope user --transport http context7 \
  https://mcp.context7.com/mcp

# 全局安装带认证的 HTTP 服务
claude mcp add --scope user --transport http secure-api \
  https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

1
2
3
4
5
6
7
8
9
10
11

# 三、传输方式（Transport）

MCP Server 支持三种传输方式：

# 3.1 stdio（本地进程）

最常见的方式，Server 作为本地子进程运行，通过标准输入输出通信。

# Python 服务
claude mcp add markitdown -- python -m markitdown_mcp

# Node.js 服务
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# 带环境变量
claude mcp add --env API_KEY=xxx --transport stdio myapi -- npx -y myapi-mcp-server

1
2
3
4
5
6
7
8

💡 -- 双横线用于分隔 Claude Code 的参数和 Server 的启动命令。-- 之后的内容原样传给 Server。

# 3.2 HTTP（远程服务）

推荐用于远程 MCP Server，支持 OAuth 认证。

# 基本语法
claude mcp add --transport http <name> <url>

# 示例：连接 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带 Bearer Token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

1
2
3
4
5
6
7
8
9

# 3.3 SSE（已弃用）

SSE（Server-Sent Events）传输已被弃用，建议使用 HTTP 替代。部分旧服务仍只提供 SSE 端点：

claude mcp add --transport sse asana https://mcp.asana.com/sse

# 3.4 WebSocket

适用于需要服务端主动推送事件的场景：

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

1
2

# 四、使用 JSON 直接添加（add-json）

当 Server 配置较复杂，或从其他客户端（Claude Desktop / Cursor）迁移时，可以用 JSON 直接添加：

# 基本语法
claude mcp add-json <name> '<json-config>'

# 示例：添加 stdio 服务
claude mcp add-json markitdown \
  '{"command":"python","args":["-m","markitdown_mcp"]}'

# 示例：添加 HTTP 服务
claude mcp add-json notion \
  '{"type":"http","url":"https://mcp.notion.com/mcp"}'

# 示例：添加带环境变量的 stdio 服务
claude mcp add-json airtable \
  '{"command":"npx","args":["-y","airtable-mcp-server"],"env":{"AIRTABLE_API_KEY":"YOUR_KEY"}}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 五、查看已安装的 MCP Server

# 5.1 列出所有 Server

claude mcp list

输出示例：

✔ markitdown      (local)    stdio
✔ filesystem      (user)     stdio
✘ notion          (local)    http    Failed to connect

1
2
3

状态说明：

状态	含义
`✔ Connected`	正常可用
`! Connected · tools fetch failed`	已连接但无法获取工具列表
`! Needs authentication`	需要浏览器登录或 Token
`✘ Failed to connect`	连接失败
`⏸ Pending approval`	项目级 Server，等待批准

# 5.2 查看单个 Server 详情

claude mcp get markitdown

会显示 Server 的完整配置（命令、参数、环境变量、传输方式、作用范围）。

# 5.3 在会话中查看（/mcp 命令）

在 Claude Code 会话中输入：

/mcp

会列出当前会话可用的所有 MCP Server 及其状态。

# 六、卸载 MCP Server

# 6.1 基本卸载

# 按名称卸载
claude mcp remove markitdown

1
2

会自动从对应作用范围的配置文件中移除。输出示例：

Removed MCP server "markitdown" from local config
File modified: /home/user/.claude.json

1
2

# 6.2 卸载指定级别的 Server

如果同名 Server 存在于多个级别，可以指定级别卸载：

# 仅卸载 user 级别
claude mcp remove --scope user markitdown

# 仅卸载 project 级别
claude mcp remove --scope project markitdown

1
2
3
4
5

# 6.3 清理项目级配置

如果是 project 级别的 Server，可以直接编辑 .mcp.json 文件：

# 查看当前配置
cat .mcp.json

# 手动编辑，删除对应条目
vim .mcp.json

1
2
3
4
5

# 6.4 批量卸载

Claude Code 没有内置的批量卸载命令，但可以结合 shell 实现：

# 列出所有 local 级别的 Server 名称并逐个卸载
claude mcp list | grep '(local)' | awk '{print $2}' | \
  while read name; do claude mcp remove "$name"; done

1
2
3

# 七、更改 Server 作用范围

如果想把一个 local 级别的 Server 提升为 user 级别（全局可用），没有直接的「迁移」命令，需要先卸载再重新添加：

# 1. 卸载 local 级别
claude mcp remove markitdown

# 2. 以 user 级别重新添加
claude mcp add --scope user markitdown -- python -m markitdown_mcp

1
2
3
4
5

# 八、常见问题

# 8.1 Server 连接失败

# 查看详细错误
claude mcp get <name>

# 常见原因：
# 1. 命令路径错误 → 检查 which python / which npx
# 2. 缺少环境变量 → 用 --env 补充
# 3. 网络问题（HTTP 类型）→ 检查 URL 可达性
# 4. Python/Node 版本过低 → 确认 >= Python 3.10 / Node 18

1
2
3
4
5
6
7
8

# 8.2 `--` 双横线的作用

-- 用于分隔 Claude Code 自身参数和 Server 启动命令。没有 -- 的话，Claude Code 会把 Server 的参数当作自己的参数解析：

# ❌ 错误：--port 会被 Claude Code 解析
claude mcp add myserver --transport stdio python server.py --port 8080

# ✅ 正确：-- 之后的内容原样传给 Server
claude mcp add myserver --transport stdio -- python server.py --port 8080

1
2
3
4
5

# 8.3 环境变量传递

# 单个环境变量
claude mcp add --env API_KEY=xxx myapi -- npx -y myapi-server

# 多个环境变量
claude mcp add \
  --env API_KEY=xxx \
  --env DB_URL=postgresql://localhost:5432/mydb \
  myapi -- npx -y myapi-server

1
2
3
4
5
6
7
8

# 8.4 Windows 下的路径问题

Windows 下使用 stdio Server 时，注意路径格式：

# Windows 路径用正斜杠或双反斜杠
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem C:/Users/blog

# 或者用 JSON 格式
claude mcp add-json filesystem \
  '{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","C:\\Users\\blog"]}'

1
2
3
4
5
6

# 8.5 禁用而不卸载

在会话中使用 /mcp 命令可以临时禁用某个 Server，不删除配置：

/mcp
# 然后选择对应 Server 进行 disable

1
2

项目级 Server 也可以在 ~/.claude.json 中添加 disabledMcpServers 列表：

{
  "disabledMcpServers": ["notion"]
}

1
2
3

# 九、实战示例

# 9.1 安装 markitdown（Markdown 转换工具）

# user 级别安装，所有项目可用
claude mcp add --scope user markitdown -- python -m markitdown_mcp

# 验证
claude mcp list

# 使用：在 Claude Code 会话中
claude
> 用 markitdown 把这个 PDF 转成 markdown: /path/to/file.pdf

1
2
3
4
5
6
7
8
9

# 9.2 安装 filesystem（文件系统访问）

# local 级别，限定访问 /home/blog 目录
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/blog

1
2

# 9.3 安装 context7（文档搜索，HTTP）

# user 级别，全局可用
claude mcp add --scope user --transport http context7 https://mcp.context7.com/mcp

1
2

# 9.4 安装 GitHub MCP

# 带认证 Token
claude mcp add --scope user --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx \
  github -- npx -y @modelcontextprotocol/server-github

1
2
3

# 十、速查表

操作	命令
添加（local，默认）	`claude mcp add <name> -- <command>`
添加（user，全局）	`claude mcp add --scope user <name> -- <command>`
添加（project，团队）	`claude mcp add --scope project <name> -- <command>`
添加 HTTP 服务	`claude mcp add --transport http <name> <url>`
添加 JSON 配置	`claude mcp add-json <name> '<json>'`
查看所有	`claude mcp list`
查看详情	`claude mcp get <name>`
卸载	`claude mcp remove <name>`
会话内查看	`/mcp`

# 总结

local（默认）：个人项目内使用，配置在 ~/.claude.json
project：团队共享，配置在 .mcp.json，可提交 Git
user：全局可用，配置在 ~/.claude.json 全局条目
stdio 传输用 -- 分隔参数，HTTP 传输用 --transport http
卸载用 claude mcp remove <name>，指定级别加 --scope

合理使用三个级别，可以让 MCP 配置既灵活又安全：个人工具用 user 级别，团队工具用 project 级别，临时测试用 local 级别。

本文基于 Claude Code 官方文档整理，最后更新：2026年9月

#Claude Code #MCP #AI编程 #Model Context Protocol

上次更新: 2026/9/6 00:37:17

← Claude Code Java 插件介绍 MCP与Skill选择指南→

Claude Code MCP 安装与卸载指南

# 一、MCP 是什么

# 二、三种安装级别（Scope）

# 2.1 local 级别（默认）

# 2.2 project 级别（团队共享）

# 2.3 user 级别（全局可用）

# 三、传输方式（Transport）

# 3.1 stdio（本地进程）

# 3.2 HTTP（远程服务）

# 3.3 SSE（已弃用）

# 3.4 WebSocket

# 四、使用 JSON 直接添加（add-json）

# 五、查看已安装的 MCP Server

# 5.1 列出所有 Server

# 5.2 查看单个 Server 详情

# 5.3 在会话中查看（/mcp 命令）

# 六、卸载 MCP Server

# 6.1 基本卸载

# 6.2 卸载指定级别的 Server

# 6.3 清理项目级配置

# 6.4 批量卸载

# 七、更改 Server 作用范围

# 八、常见问题

# 8.1 Server 连接失败

# 8.2 -- 双横线的作用

# 8.3 环境变量传递

# 8.4 Windows 下的路径问题

# 8.5 禁用而不卸载

# 九、实战示例

# 9.1 安装 markitdown（Markdown 转换工具）

# 9.2 安装 filesystem（文件系统访问）

# 9.3 安装 context7（文档搜索，HTTP）

# 9.4 安装 GitHub MCP

# 十、速查表

# 总结

# 8.2 `--` 双横线的作用