Claude Code添加MCP Server教程：项目级与全局级配置详解

前言

在之前的文章中，我们已经介绍了如何在 VSCode 中集成 Claude Code，并配置 DeepSeek 等模型。但要真正发挥 Claude Code 的潜力，还需要为它扩展 MCP（Model Context Protocol）Server 的能力。本文将详细讲解如何通过命令行和配置文件，为 Claude Code 添加项目级和全局级的 MCP Server。

什么是MCP Server

MCP Server 是 Claude Code 生态中的重要扩展机制，它允许 AI 助手连接外部工具和服务，从而获得更强大的能力。

MCP（Model Context Protocol，模型上下文协议）是由 Anthropic 于 2024 年底推出的一项开放标准协议，旨在为大语言模型提供统一的外部工具和数据源接入方式。在 MCP 出现之前，每个 AI 工具与外部服务的集成都需要单独开发适配器，导致生态碎片化严重。MCP 借鉴了 LSP（Language Server Protocol）的设计理念——正如 LSP 统一了编辑器与编程语言服务之间的通信协议一样，MCP 统一了 AI 模型与外部工具之间的交互标准。MCP 采用客户端-服务器架构，其中 AI 助手（如 Claude Code）作为客户端，各种工具和服务作为 MCP Server 提供能力。这种架构使得开发者只需实现一次 MCP Server，就能被所有支持 MCP 协议的 AI 客户端调用。

常见的 MCP Server 包括：

GitNationals：为 Git 仓库管理的代码构建知识图谱，帮助 AI 更好地理解项目结构。知识图谱（Knowledge Graph）是一种以图结构组织信息的技术，由节点（实体）和边（关系）构成。在代码仓库的场景中，知识图谱将文件、函数、类、模块等代码元素作为节点，将调用关系、继承关系、依赖关系等作为边，构建出一张完整的代码关系网络。相比传统的全文搜索或简单的文件树浏览，知识图谱能让 AI 理解代码的语义结构——例如，当 AI 需要修改某个函数时，它可以通过知识图谱快速定位所有调用该函数的位置、该函数依赖的其他模块，以及可能受影响的测试用例。
Hanset：基于 Git 的记忆系统，让 AI 在多次对话间保持上下文记忆。大语言模型的一个固有限制是「无状态性」——每次对话都是独立的，模型不会自动记住之前的交互内容。基于 Git 的记忆系统通过将对话中的关键信息（如项目约定、架构决策、用户偏好等）持久化存储到 Git 仓库中来解决这一问题。当新的对话开始时，MCP Server 会检索相关的历史记忆，作为上下文注入到当前对话中。选择 Git 作为存储后端的优势在于：天然支持版本控制，可以追溯记忆的变更历史；支持分支管理，不同项目可以维护独立的记忆空间；且 Git 仓库可以通过远程仓库在团队间共享，实现团队级别的 AI 知识积累。

Git的记忆系统

这两个 MCP Server 在实际开发中非常实用，本文将以它们为例，演示完整的添加流程。

通过命令行添加MCP Server

两种连接方式

Claude Code 支持两种类型的 MCP Server 连接方式：

stdio（标准输入输出）：适用于本地运行的 MCP Server，通过本地命令启动
HTTP：适用于远程部署的 MCP Server，通过 HTTP 地址连接

stdio（Standard Input/Output，标准输入输出）是 Unix/Linux 系统中最基础的进程间通信方式。在 MCP 的 stdio 模式下，Claude Code 会以子进程的方式启动 MCP Server，通过标准输入（stdin）发送请求，通过标准输出（stdout）接收响应。这种方式的优势在于无需网络配置，延迟极低，且天然具备进程级别的安全隔离。HTTP 传输模式则基于 Server-Sent Events（SSE）或标准 HTTP 请求实现，适用于 MCP Server 部署在远程服务器或容器中的场景。HTTP 模式支持跨网络访问，可以通过 Header 携带认证令牌（如 Bearer Token），适合团队共享的服务。两种模式在功能上完全等价，选择哪种取决于部署架构。

命令行工具提供了 claude mcp add 命令来添加 MCP Server，语法非常直观。

添加stdio类型的MCP Server

以 GitNationals 为例，它是一个本地运行的服务，使用 stdio 方式连接：

claude mcp add GitNationals -- <command> <args>

其中需要指定名称（GitNationals）、两个横杠后跟具体的命令行及参数。执行后，MCP Server 会被添加到项目的配置文件中。

添加MCP Server配置

添加HTTP类型的MCP Server

对于 Hanset 这样部署在内网的服务，使用 HTTP 方式连接：

claude mcp add Hanset --transport http <URL>

如果是内网服务且不需要授权，可以省略 Header 配置。添加完成后，可以在配置文件中看到两个 MCP Server 的信息——一个是 HTTP 类型，一个是 stdio 类型。

验证MCP Server连接状态

添加完成后，通过以下命令检查连接状态：

claude mcp list

如果显示 GitNexus 和 Hanset 都处于「连接状态」，说明 MCP Server 配置正常，可以正常使用。

MCP Server连接状态验证

在 VSCode 中，可能需要重启扩展才能看到新添加的 MCP Server。重启后，在 Claude Code 面板中即可查看到已配置的 MCP 列表。

项目级与全局级MCP配置

默认行为：项目级配置

这里有一个非常关键的细节：通过命令行添加的 MCP Server 默认是项目级别的。

Claude Code 采用分层配置的设计模式，这在开发工具中是一种常见的最佳实践。类似于 Git 的配置分层（系统级 /etc/gitconfig、用户级 ~/.gitconfig、仓库级 .git/config），Claude Code 的配置也遵循「就近优先」原则——项目级配置会覆盖全局级配置中的同名设置。这种设计的核心价值在于灵活性与一致性的平衡：全局配置确保基础工具在所有项目中可用，项目级配置则允许针对特定项目进行定制。例如，一个前端项目可能需要连接设计稿解析的 MCP Server，而后端项目则需要数据库 Schema 查询的 MCP Server，这些专用工具只需在对应项目中配置即可。

配置信息存储在项目目录下的 .claude.json 文件中，属于 project 范围。这意味着：

在当前项目目录下，MCP Server 正常可用
切换到其他目录或打开其他项目时，MCP Server 将不可见

实际验证也证实了这一点：当切换到其他目录后，执行 claude mcp list 会发现列表为空，VSCode 中同样看不到任何 MCP Server。

如何配置全局MCP Server

如果希望所有项目都能使用同一组 MCP Server，需要将配置提升为全局级别。具体操作步骤如下：

打开配置文件：找到用户目录下的 .claude.json 文件（通常位于 ~/.claude.json）
复制 MCP 节点：将 project 下的 MCP Server 配置节点复制出来
移至根级别：将复制的配置放到 JSON 文件的根层级下
调整缩进：确保 JSON 格式正确
清理项目级配置（可选）：如果不再需要项目级配置，可以删除 project 下的对应节点

修改配置文件实现全局MCP

值得注意的是，.claude.json 文件采用 JSON 格式存储，项目级的配置文件可以纳入版本控制（如 Git），方便团队成员共享项目级的 MCP 配置，而用户目录下的全局配置则属于个人环境设置，通常不应提交到代码仓库中。

修改完成后：

命令行验证：在任意目录下执行 claude mcp list 即可看到 MCP Server
VSCode 验证：需要重启 VSCode，之后在任意项目中都能看到已配置的 MCP Server

这样就实现了为当前登录用户添加全局 MCP Server，所有项目都能共享这些扩展能力，无需逐个项目重复配置。

配置要点总结

配置层级	适用场景	配置位置
项目级（Project）	特定项目专用的 MCP Server	项目目录下 `.claude.json` 的 `project` 节点
全局级（User）	所有项目通用的 MCP Server	用户目录下 `.claude.json` 的根节点

实践建议

通用工具建议全局配置：像 GitNationals（知识图谱）和 Hanset（记忆系统）这类通用工具，建议配置为全局级别，避免在每个项目中重复操作
专用工具保持项目配置：如果某个 MCP Server 只在特定项目中使用，保持项目级配置即可，不会影响其他项目
先命令行后手动调整：推荐先通过 claude mcp add 命令快速添加，再手动编辑配置文件调整作用域
修改后注意重启：修改配置后，VSCode 通常需要重启才能生效，命令行则可能需要切换目录后重新验证
团队协作时善用项目级配置：将项目级的 .claude.json 纳入 Git 版本控制，团队成员克隆仓库后即可自动获得项目所需的 MCP Server 配置，无需手动逐一添加，大幅降低新成员的环境搭建成本

掌握了 MCP Server 的配置方法，就能让 Claude Code 在 VSCode 中发挥更强大的能力，真正成为开发过程中的得力助手。