# Claude Code MCP 配置指南

**创建时间**: 2026-01-29 11:50:00 CST
**父技能**: ops-tools

## 概述

MCP (Model Context Protocol) 是 Claude Code 与外部服务集成的标准协议。

## 配置文件位置

| 配置文件 | 作用域 | 说明 |
|----------|--------|------|
| `~/.claude/.mcp.json` | 用户级（推荐） | 所有项目共享 |
| `.claude/mcp.json` | 项目级 | 仅当前项目生效 |

## 配置模板（stdio 模式）

```json
{
  "mcpServers": {
    "<服务名称>": {
      "type": "stdio",
      "command": "node",
      "args": ["<服务入口文件路径>"],
      "env": {
        "API_BASE": "<API基础URL>",
        "API_TOKEN": "<PAT令牌>",
        "NODE_ENV": "production"
      }
    }
  }
}
```

**参数说明**：

| 参数 | 说明 | 示例 |
|------|------|------|
| `type` | 传输类型，固定为 `stdio` | `stdio` |
| `command` | 启动命令 | `node` |
| `args` | 入口文件路径 | `["dist/index.js"]` |
| `env` | 环境变量 | API 地址、PAT 令牌 |

## ai-proj MCP 配置

**配置文件** (`~/.claude/.mcp.json`):

```json
{
  "mcpServers": {
    "ai-proj": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/coolbuy-dev/coding/new-ai-proj/mcp-task-bridge/dist/index.js"],
      "env": {
        "TASK_API_BASE": "https://ai.pipexerp.com/api/v1",
        "TASK_API_TOKEN": "aiproj_pk_2ecf8f8728b70afd4420af3875f4f7505c9fe8231a4771972b0f385aa1c75099",
        "NODE_ENV": "production"
      }
    }
  }
}
```

### 环境变量

| 变量 | 说明 |
|------|------|
| `TASK_API_BASE` | `https://ai.pipexerp.com/api/v1` |
| `TASK_API_TOKEN` | `aiproj_pk_2ecf8f8728b70afd4420af3875f4f7505c9fe8231a4771972b0f385aa1c75099` |

### 前置条件

```bash
# 编译 mcp-task-bridge
cd /Users/coolbuy-dev/coding/new-ai-proj/mcp-task-bridge
npm run build
```

### 验证步骤

```bash
# 1. 手动测试服务
cd /Users/coolbuy-dev/coding/new-ai-proj/mcp-task-bridge
TASK_API_BASE="https://ai.pipexerp.com/api/v1" \
TASK_API_TOKEN="aiproj_pk_2ecf8f8728b70afd4420af3875f4f7505c9fe8231a4771972b0f385aa1c75099" \
node dist/index.js

# 2. 测试 API 连接
curl -s "https://ai.pipexerp.com/api/v1/projects" \
  -H "Authorization: Bearer aiproj_pk_2ecf8f8728b70afd4420af3875f4f7505c9fe8231a4771972b0f385aa1c75099" | head -c 200

# 3. Claude Code 重连
/mcp
```

## 开发新 MCP 服务

### 步骤 1: 创建项目

```bash
mkdir my-mcp-service && cd my-mcp-service
npm init -y
npm install @modelcontextprotocol/sdk
```

### 步骤 2: 实现服务

```typescript
// src/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-mcp-service",
  version: "1.0.0",
}, { capabilities: { tools: {} } });

// 注册和实现工具...

const transport = new StdioServerTransport();
await server.connect(transport);
```

### 步骤 3: 编译和配置

```bash
npm run build
vim ~/.claude/.mcp.json  # 添加配置
claude  # 重启 Claude Code
```

## 故障排查

### MCP 连接失败

```bash
# 1. 检查配置文件
cat ~/.claude/.mcp.json | jq .

# 2. 检查服务文件
ls -la <服务路径>/dist/index.js

# 3. 手动运行服务
<环境变量> node dist/index.js
```

**常见原因**：
- 服务未编译 → `npm run build`
- Token 无效 → 重新生成 PAT
- `/mcp` 无效 → 重启 Claude Code

### 认证失败 (401)

```bash
curl -s "<API_BASE>/auth/me" -H "Authorization: Bearer <TOKEN>"
```

## 相关文件

| 文件 | 说明 |
|------|------|
| `~/.claude/.mcp.json` | MCP 配置 |
| `mcp-task-bridge/dist/index.js` | ai-proj MCP 服务 |