MCP 服务器配置说明

配置文件层级

Claude Code 的 MCP 服务器配置分布在两个层级，生效逻辑不同：

配置文件	路径	作用
全局用户配置（生效 ✅）	`C:\Users\YWH18\.claude.json`	对话中实际加载 MCP 服务器的位置，全局生效
项目级 MCP 配置（生效 ✅）	`C:\Users\YWH18\.claude\.mcp.json`	同目录及子目录下的项目可用的 MCP 配置

⚠️ 关键说明：.mcp.json 是项目级 MCP 配置，Claude Code 在对话过程中会加载它。配置优先级从高到低为：project/.claude/settings.local.json → project/.claude.json → .mcp.json（向上查找最近的） → ~/.claude.json（全局兜底）。多个 scope 定义了同名服务器时会产生冲突警告，需删除多余的。每个项目还可以在 .claude.json 的 projects.<path>.mcpServers 中定义项目专属的 MCP 服务器。

实际生效的 MCP 服务器（全局）

以下配置定义在 C:\Users\YWH18\.claude.json 的 mcpServers 中，所有项目均可用：

1. GitHub MCP

{
  "github": {
    "type": "stdio",
    "command": "mcp-server-github",
    "args": [],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}",
      "NODE_OPTIONS": "--use-system-ca"
    }
  }
}

安装方式：npm install -g @modelcontextprotocol/server-github
安装路径：D:\AI\npm_global\node_modules\@modelcontextprotocol\server-github\
可执行命令：D:\AI\npm_global\mcp-server-github
环境变量：GITHUB_TOKEN 在系统环境变量中设置
NODE_OPTIONS：--use-system-ca 确保使用 Windows 系统证书存储，解决企业网络或代理环境下的 CA 证书问题

2. Tavily MCP（搜索）

{
  "tavily": {
    "type": "http",
    "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-dev-xxx"
  }
}

连接方式：HTTP（而非 stdio 命令），通过 URL 参数传递 API Key
type 为 http：Claude Code 直接通过 HTTP 连接 Tavily MCP 服务，无需本地安装 npm 包
API Key：直接嵌入 URL 中，通过 query 参数 tavilyApiKey 传递，使用 dev 级别密钥

3. agnes-vision（Agnes 视觉）

{
  "agnes-vision": {
    "type": "stdio",
    "command": "C:/Users/YWH18/mcp-agnes-vision/agnes-vision.exe",
    "args": [],
    "timeout": 300000,
    "env": {}
  }
}

独立 EXE，不依赖 Python
支持 6 个工具：看图问答（describe_image）、裁剪（vision_crop）、取色（vision_colors）、像素对比（vision_pixel_diff）、抠图（vision_extract_foreground）、定位（vision_ground）
底层调用 Agnes 2.0 Flash 云端 API，本地只做像素操作

项目级 MCP 服务器

在 C:\Users\YWH18\.claude.json 的 projects.<path>.mcpServers 中，可以为特定项目单独配置 MCP 服务器。当前各项目的 MCP 配置：

项目路径	配置的 MCP 服务器
`D:/AI/AI_Project/my_note`	`sensenova-vision`（已废弃）
其他项目	无 / 空

注：sensenova-vision 和 glm-vision 已废弃，统一由全局的 agnes-vision 替代。旧项目配置虽残留在 .claude.json 中，但 MCP 服务器已不存在，不生效。

兜底配置（`.mcp.json`，项目级生效）

C:\Users\YWH18\.claude\.mcp.json 完整内容：

{
  "mcpServers": {
    "github": {
      "command": "mcp-server-github",
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}",
        "NODE_OPTIONS": "--use-system-ca"
      }
    },
    "tavily": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-dev-xxx"
    },
    "agnes-vision": {
      "command": "C:\\Users\\YWH18\\mcp-agnes-vision\\agnes-vision.exe",
      "args": [],
      "timeout": 300000
    }
  }
}

注意：github 在 .mcp.json 和 .claude.json 中均有定义，但配置一致，不会冲突。tavily 和 agnes-vision 与全局配置相同，保持同步。

安装方式对比：全局安装 vs npx

项	全局安装（当前方案 ✅）	npx 方案（旧方案 ❌）
命令	直接调用（如 `mcp-server-github`）	`npx -y @modelcontextprotocol/server-github`
启动速度	快，无额外检查	慢，需检查缓存
缓存影响	清 npm 缓存不影响运行	清缓存后需重新下载
路径	`D:\AI\npm_global\node_modules\`	`D:\AI\node_cache\_npx\<hash>\`

`claude mcp` 命令详解

添加 MCP 服务器

# 基本语法
claude mcp add [options] <名称> <命令或URL> [参数...]

命令结构拆解：

claude mcp add   --transport http   --scope user   tavily   https://mcp.tavily.com/mcp/?tavilyApiKey=xxx
└──────┬─────┘   └───────┬───────┘   └─────┬────┘   └─┬──┘   └──────────────────┬──────────────────┘
       │                  │                 │          │                         │
  固定前缀              选项              选项       名称（必填）              命令或 URL（必填）
  "我要添加              传输方式          配置范围   给这个服务器                实际连接的地址
  一个 MCP 服务器"        = HTTP 连接       = 全局     起个名字叫 "tavily"        或本地可执行文件

部分	含义	说明
`claude mcp add`	固定前缀	告诉 Claude Code "我要添加一个 MCP 服务器"
`--transport http`	传输方式	不写默认 `stdio`（本地进程通信）。HTTP 用于远程服务直接连接
`--scope user`	配置范围	不写默认 `local`（仅当前项目）。`user` 表示写入全局配置，所有项目生效
`tavily`	服务器名称	自定义唯一标识，`claude mcp list` 中显示的名字
`https://...`	目标地址	对 HTTP 传输来说是服务端 URL；对 stdio 来说是本地可执行文件路径

类比 git 命令：claude mcp add --transport http --scope user tavily https://... 相当于 git remote add --fetch origin https://...，结构完全一致（CLI → 子系统 → 动作 → 参数 → 名称 → 目标地址）。

和手动编辑 JSON 的对应关系：

claude mcp add --transport http --scope user tavily https://mcp.tavily.com/mcp/?tavilyApiKey=xxx

等价于在 ~/.claude.json 的 mcpServers 中写入：

{
  "mcpServers": {
    "tavily": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=xxx"
    }
  }
}

用命令的好处：不用手动编辑 JSON、不用担心路径转义、JSON 格式错误等问题，Claude Code 自己帮你写配置文件。

--scope 参数说明（关键）：

值	写入位置	生效范围
`user`（推荐）	`~/.claude.json` 的全局 `mcpServers`	所有项目均可用
`local`（默认）	当前项目目录下的 `.claude/settings.local.json`	仅当前项目
`project`	当前项目目录下的 `.claude.json`（会提交到 Git）	仅当前项目，但会进版本控制

实际示例：

# ★ 全局配置（--scope user）：写入 ~/.claude.json，所有项目生效
# 添加 HTTP 类型（如 Tavily 搜索）
claude mcp add --transport http --scope user tavily https://mcp.tavily.com/mcp/?tavilyApiKey=你的APIKey

# 添加 HTTP 类型 + 自定义请求头（全局）
claude mcp add --transport http --scope user corridor https://app.corridor.dev/api/mcp --header "Authorization: Bearer ..."

# 添加 stdio 类型（全局，如 EXE 或 npm 包）
claude mcp add --scope user github -- mcp-server-github

# 添加 stdio 类型 + 环境变量（全局）
claude mcp add --scope user my-server -e API_KEY=xxx -- npx my-mcp-server

# 添加 stdio 类型 + 子进程参数（全局）
claude mcp add --scope user my-server -- my-command --some-flag arg1

`claude mcp add` 选项参考

选项	说明
`-t, --transport <type>`	传输类型：`stdio`、`sse`、`http`。默认 stdio
`-e, --env <key=value>`	设置环境变量，可重复使用
`-H, --header <header>`	设置 WebSocket 请求头，可重复使用
`-s, --scope <scope>`	配置范围：`local`（当前项目）、`user`（当前用户）、`project`（项目级）。默认 `local`
`--client-id <id>`	OAuth client ID（用于 HTTP/SSE 服务器）
`--client-secret`	交互式输入 OAuth client secret
`--callback-port <port>`	固定 OAuth 回调端口（用于需要预注册重定向 URI 的服务器）

npm 包管理命令

# 查看全局安装的 npm 包
npm list -g --depth=0

# 查看全局安装路径
npm root -g

# 更新 MCP 包
npm update -g tavily-mcp
npm update -g @modelcontextprotocol/server-github

# MCP 服务器配置说明

## 配置文件层级

Claude Code 的 MCP 服务器配置分布在两个层级，**生效逻辑不同**：

| 配置文件                    | 路径                               | 作用                                          |
| --------------------------- | ---------------------------------- | --------------------------------------------- |
| **全局用户配置**（生效 ✅） | `C:\Users\YWH18\.claude.json`     | 对话中**实际加载** MCP 服务器的位置，全局生效 |
| 项目级 MCP 配置（生效 ✅）  | `C:\Users\YWH18\.claude\.mcp.json` | 同目录及子目录下的项目可用的 MCP 配置         |

> ⚠️ **关键说明**：`.mcp.json` 是项目级 MCP 配置，Claude Code 在对话过程中**会加载**它。配置优先级从高到低为：`project/.claude/settings.local.json` → `project/.claude.json` → `.mcp.json`（向上查找最近的） → `~/.claude.json`（全局兜底）。多个 scope 定义了同名服务器时会产生冲突警告，需删除多余的。每个项目还可以在 `.claude.json` 的 `projects.<path>.mcpServers` 中定义项目专属的 MCP 服务器。

## 实际生效的 MCP 服务器（全局）

以下配置定义在 `C:\Users\YWH18\.claude.json` 的 `mcpServers` 中，**所有项目均可用**：

### 1. GitHub MCP

```json
{
  "github": {
    "type": "stdio",
    "command": "mcp-server-github",
    "args": [],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}",
      "NODE_OPTIONS": "--use-system-ca"
    }
  }
}
```

- **安装方式**：`npm install -g @modelcontextprotocol/server-github`
- **安装路径**：`D:\AI\npm_global\node_modules\@modelcontextprotocol\server-github\`
- **可执行命令**：`D:\AI\npm_global\mcp-server-github`
- **环境变量**：`GITHUB_TOKEN` 在系统环境变量中设置
- **`NODE_OPTIONS`**：`--use-system-ca` 确保使用 Windows 系统证书存储，解决企业网络或代理环境下的 CA 证书问题

### 2. Tavily MCP（搜索）

```json
{
  "tavily": {
    "type": "http",
    "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-dev-xxx"
  }
}
```

- **连接方式**：HTTP（而非 stdio 命令），通过 URL 参数传递 API Key
- **type 为 `http`**：Claude Code 直接通过 HTTP 连接 Tavily MCP 服务，无需本地安装 npm 包
- **API Key**：直接嵌入 URL 中，通过 query 参数 `tavilyApiKey` 传递，使用 dev 级别密钥

### 3. agnes-vision（Agnes 视觉）

```json
{
  "agnes-vision": {
    "type": "stdio",
    "command": "C:/Users/YWH18/mcp-agnes-vision/agnes-vision.exe",
    "args": [],
    "timeout": 300000,
    "env": {}
  }
}
```

- 独立 EXE，不依赖 Python
- 支持 6 个工具：看图问答（describe_image）、裁剪（vision_crop）、取色（vision_colors）、像素对比（vision_pixel_diff）、抠图（vision_extract_foreground）、定位（vision_ground）
- 底层调用 Agnes 2.0 Flash 云端 API，本地只做像素操作

## 项目级 MCP 服务器

在 `C:\Users\YWH18\.claude.json` 的 `projects.<path>.mcpServers` 中，可以为特定项目单独配置 MCP 服务器。当前各项目的 MCP 配置：

| 项目路径                                          | 配置的 MCP 服务器                 |
| ------------------------------------------------- | --------------------------------- |
| `D:/AI/AI_Project/my_note`                        | `sensenova-vision`（已废弃）      |
| 其他项目                                          | 无 / 空                           |

> 注：`sensenova-vision` 和 `glm-vision` 已废弃，统一由全局的 `agnes-vision` 替代。旧项目配置虽残留在 `.claude.json` 中，但 MCP 服务器已不存在，不生效。

## 兜底配置（`.mcp.json`，项目级生效）

`C:\Users\YWH18\.claude\.mcp.json` 完整内容：

```json
{
  "mcpServers": {
    "github": {
      "command": "mcp-server-github",
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}",
        "NODE_OPTIONS": "--use-system-ca"
      }
    },
    "tavily": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-dev-xxx"
    },
    "agnes-vision": {
      "command": "C:\\Users\\YWH18\\mcp-agnes-vision\\agnes-vision.exe",
      "args": [],
      "timeout": 300000
    }
  }
}
```

> 注意：`github` 在 `.mcp.json` 和 `.claude.json` 中均有定义，但配置一致，不会冲突。`tavily` 和 `agnes-vision` 与全局配置相同，保持同步。

## 安装方式对比：全局安装 vs npx

| 项       | 全局安装（当前方案 ✅）            | npx 方案（旧方案 ❌）                        |
| -------- | ---------------------------------- | -------------------------------------------- |
| 命令     | 直接调用（如 `mcp-server-github`） | `npx -y @modelcontextprotocol/server-github` |
| 启动速度 | 快，无额外检查                     | 慢，需检查缓存                               |
| 缓存影响 | 清 npm 缓存不影响运行              | 清缓存后需重新下载                           |
| 路径     | `D:\AI\npm_global\node_modules\`   | `D:\AI\node_cache\_npx\<hash>\`              |

## `claude mcp` 命令详解

### 添加 MCP 服务器

```bash
# 基本语法
claude mcp add [options] <名称> <命令或URL> [参数...]
```

**命令结构拆解：**

```
claude mcp add   --transport http   --scope user   tavily   https://mcp.tavily.com/mcp/?tavilyApiKey=xxx
└──────┬─────┘   └───────┬───────┘   └─────┬────┘   └─┬──┘   └──────────────────┬──────────────────┘
       │                  │                 │          │                         │
  固定前缀              选项              选项       名称（必填）              命令或 URL（必填）
  "我要添加              传输方式          配置范围   给这个服务器                实际连接的地址
  一个 MCP 服务器"        = HTTP 连接       = 全局     起个名字叫 "tavily"        或本地可执行文件
```

| 部分               | 含义       | 说明                                                                  |
| ------------------ | ---------- | --------------------------------------------------------------------- |
| `claude mcp add`   | 固定前缀   | 告诉 Claude Code "我要添加一个 MCP 服务器"                            |
| `--transport http` | 传输方式   | 不写默认 `stdio`（本地进程通信）。HTTP 用于远程服务直接连接           |
| `--scope user`     | 配置范围   | 不写默认 `local`（仅当前项目）。`user` 表示写入全局配置，所有项目生效 |
| `tavily`           | 服务器名称 | 自定义唯一标识，`claude mcp list` 中显示的名字                        |
| `https://...`      | 目标地址   | 对 HTTP 传输来说是服务端 URL；对 stdio 来说是本地可执行文件路径       |

> 类比 `git` 命令：`claude mcp add --transport http --scope user tavily https://...` 相当于 `git remote add --fetch origin https://...`，结构完全一致（CLI → 子系统 → 动作 → 参数 → 名称 → 目标地址）。

**和手动编辑 JSON 的对应关系：**

```bash
claude mcp add --transport http --scope user tavily https://mcp.tavily.com/mcp/?tavilyApiKey=xxx
```

等价于在 `~/.claude.json` 的 `mcpServers` 中写入：

```json
{
  "mcpServers": {
    "tavily": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=xxx"
    }
  }
}
```

> 用命令的好处：不用手动编辑 JSON、不用担心路径转义、JSON 格式错误等问题，Claude Code 自己帮你写配置文件。

**`--scope` 参数说明（关键）：**

| 值              | 写入位置                                        | 生效范围                   |
| --------------- | ----------------------------------------------- | -------------------------- |
| `user`（推荐）  | `~/.claude.json` 的全局 `mcpServers`            | **所有项目**均可用         |
| `local`（默认） | 当前项目目录下的 `.claude/settings.local.json`  | **仅当前项目**             |
| `project`       | 当前项目目录下的 `.claude.json`（会提交到 Git） | 仅当前项目，但会进版本控制 |

**实际示例：**

```bash
# ★ 全局配置（--scope user）：写入 ~/.claude.json，所有项目生效
# 添加 HTTP 类型（如 Tavily 搜索）
claude mcp add --transport http --scope user tavily https://mcp.tavily.com/mcp/?tavilyApiKey=你的APIKey

# 添加 HTTP 类型 + 自定义请求头（全局）
claude mcp add --transport http --scope user corridor https://app.corridor.dev/api/mcp --header "Authorization: Bearer ..."

# 添加 stdio 类型（全局，如 EXE 或 npm 包）
claude mcp add --scope user github -- mcp-server-github

# 添加 stdio 类型 + 环境变量（全局）
claude mcp add --scope user my-server -e API_KEY=xxx -- npx my-mcp-server

# 添加 stdio 类型 + 子进程参数（全局）
claude mcp add --scope user my-server -- my-command --some-flag arg1
```

### `claude mcp add` 选项参考

| 选项                     | 说明                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------ |
| `-t, --transport <type>` | 传输类型：`stdio`、`sse`、`http`。默认 stdio                                         |
| `-e, --env <key=value>`  | 设置环境变量，可重复使用                                                             |
| `-H, --header <header>`  | 设置 WebSocket 请求头，可重复使用                                                    |
| `-s, --scope <scope>`    | 配置范围：`local`（当前项目）、`user`（当前用户）、`project`（项目级）。默认 `local` |
| `--client-id <id>`       | OAuth client ID（用于 HTTP/SSE 服务器）                                              |
| `--client-secret`        | 交互式输入 OAuth client secret                                                       |
| `--callback-port <port>` | 固定 OAuth 回调端口（用于需要预注册重定向 URI 的服务器）                             |

## npm 包管理命令

```bash
# 查看全局安装的 npm 包
npm list -g --depth=0

# 查看全局安装路径
npm root -g

# 更新 MCP 包
npm update -g tavily-mcp
npm update -g @modelcontextprotocol/server-github
```