166 lines
3.6 KiB
Markdown
166 lines
3.6 KiB
Markdown
# 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 服务 |
|