Claude Model Proxy MCP Server

mcp-model-proxy

一个最小的本地 MCP Server，把任意兼容 Claude Messages API 的上游包装成统一的 MCP 工具 ask_model。

注意：本项目转发的是 Claude Messages API 格式的请求。其他服务（如 OpenAI、Gemini 原生 API）与此格式不兼容，直接填入不会生效。部分中转服务或网关会把 Claude Messages API 格式转发给 GPT/Gemini，这类服务可以用，但兼容性由中转服务保证，与本项目无关。

不负责账号管理、provider 切换或流式输出。就一件事：把上游接口变成 MCP 工具，让 MCP Inspector、编辑器插件或其他支持 MCP 的客户端能直接调用。

运行模式：本项目使用 stdio 传输，必须由宿主客户端以子进程方式启动（即在 MCP 配置里指定 command 和 args）。直接运行 node server.mjs 不会监听任何端口，进程会挂起等待 stdin 输入，这是正常行为。

目录

• 系统要求
• 快速开始
• 项目结构
• 核心调用流程
• 工作原理
• MCP 工具说明
• 接入常见 MCP 客户端
• 验证方式
• 故障排查
• 已知限制
• 适用场景
• FAQ
• 安全建议

系统要求

• Node.js 18+
• npm 7+
• 可访问兼容 Claude Messages API 的上游服务的网络环境（Node.js 默认不走系统代理，如需代理请设置 HTTPS_PROXY 环境变量）

依赖包：

• @modelcontextprotocol/sdk
• zod

快速开始

1. 安装依赖

npm install

2. 设置环境变量

Windows PowerShell:

$env:CLAUDE_MCP_BASE_URL = "https://your-base-url"
$env:CLAUDE_MCP_API_KEY = "your-token"
$env:CLAUDE_MCP_MODEL = "claude-sonnet-4-5"
$env:CLAUDE_MCP_ANTHROPIC_VERSION = "2023-06-01"
$env:CLAUDE_MCP_TIMEOUT_MS = "60000"

其中 CLAUDE_MCP_ANTHROPIC_VERSION 和 CLAUDE_MCP_TIMEOUT_MS 是可选项。参考 .env.example 维护自己的本地模板，不要把真实 token 提交到仓库。

3. 用 Inspector 测试

以下命令为 PowerShell 格式（Windows），macOS/Linux 请将行末的 ` 换成 \：

npx @modelcontextprotocol/inspector --cli `
  node /path/to/mcp-model-proxy/server.mjs `
  --method tools/call `
  --tool-name ask_model `
  --tool-arg "prompt=介绍一下你自己"

4. 预期结果

// 示意，非真实数据，实际 token 数取决于模型和 prompt
{
  "model": "claude-sonnet-4-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 100,
    "output_tokens": 76
  },
  "text": "..."
}

项目结构

mcp-model-proxy/
├─ examples/
│  ├─ assets/
│  │  ├─ core-call-flow.drawio
│  │  └─ core-call-flow.svg
│  ├─ mcp-client-config.windows.json
│  ├─ mcp-client-config.macos.json
│  └─ inspector-powershell.md
├─ .env.example
├─ .gitignore
├─ CHANGELOG.md
├─ LICENSE
├─ package.json
├─ package-lock.json
├─ server.mjs
└─ README.md

其中：

• server.mjs 是 MCP Server 主入口
• examples/mcp-client-config.*.json 是不同平台的宿主客户端配置示例
• examples/assets/ 放 README 用到的流程图源文件和导出图

核心调用流程

可编辑源文件见 ./examples/assets/core-call-flow.drawio，后续如果要改节点文案、配色或布局，可以直接用 draw.io 或 next-ai-draw-io 打开继续调整。

工作原理

环境变量

URL 自动补全

以下三种写法均可：

https://example.com
https://example.com/v1
https://example.com/v1/messages

请求头

x-api-key: <your-key>
anthropic-version: 2023-06-01
content-type: application/json

返回结构

{
  "model": "claude-sonnet-4-5-20250929",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 100, "output_tokens": 76 },
  "text": "模型返回的正文"
}

MCP 工具说明

当前只暴露一个工具：ask_model

补充说明：

• 传入超过 65536 的 maxTokens 不会发到上游，而会在本地参数校验阶段直接报错
• 真实可用的输出上限仍然取决于你的上游服务和模型本身

调用示例（maxTokens 不传时默认 1024，此处显式设为 512 以演示用法）：

{
  "prompt": "介绍一下你自己",
  "model": "claude-sonnet-4-5",
  "maxTokens": 512
}

使用 system 限定模型行为：

{
  "prompt": "What is MCP?",
  "system": "You are a concise technical assistant. Reply in English only.",
  "maxTokens": 256
}

接入常见 MCP 客户端

这类客户端的接入思路都差不多：

1. 指定启动命令为 node /path/to/mcp-model-proxy/server.mjs
2. 通过环境变量传入上游地址、API Key 和默认模型
3. 在客户端工具列表里调用 ask_model

下面以 Claude Code 这类支持 JSON MCP 配置的客户端为例（Windows，使用 cmd /c 启动；macOS/Linux 见 examples/mcp-client-config.macos.json）：

Windows 上部分 MCP 宿主（如 Claude Code）需要通过 cmd /c 间接调用 node，否则会出现路径解析失败。macOS/Linux 直接用 "command": "node" 即可。

{
  "mcpServers": {
    "mcp-model-proxy": {
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "/path/to/mcp-model-proxy/server.mjs"
      ],
      "env": {
        "CLAUDE_MCP_BASE_URL": "https://your-base-url",
        "CLAUDE_MCP_API_KEY": "your-token",
        "CLAUDE_MCP_MODEL": "claude-sonnet-4-5",
        "CLAUDE_MCP_ANTHROPIC_V