ai-proj-helper/skills/ops-tools-plugin/mcp-config.md

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 模式）

{
  "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):

{
  "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

前置条件

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

验证步骤

# 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: 创建项目

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

步骤 2: 实现服务

// 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: 编译和配置

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

故障排查

MCP 连接失败

# 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)

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

相关文件

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