qiaomu-llm-mcp

把多个 LLM Provider、API Key、模型路由和多模型讨论统一成一个本地 MCP 网关。 A local MCP gateway that turns many LLM providers, API keys, routing rules, and multi-model discussions into one tool surface.

中文 | English

适合这些场景：

你同时使用 Z.ai Coding Plan、DeepSeek、OpenAI-compatible API、Anthropic-compatible API、Claude Code CLI 等多套模型。
你不想把 API Key 写进提示词、脚本或 Codex 配置里。
你希望在 Codex / Claude / 其他 MCP 客户端里用同一组工具完成：单模型调用、多模型对比、流水线、HeavySkill 式多轮讨论。
你需要让最强的主控模型主持讨论，而不是把全部判断交给某一个 Provider。

本项目是本地优先工具：Provider 注册表保存在 ~/.config/qiaomu-llm/registry.json，密钥默认放在 macOS Keychain，MCP server 只暴露“密钥是否存在”，不会返回明文 Key。

你能得到什么

安装后，MCP 客户端会看到这些工具：

工具	作用
`qllm_list_providers`	列出本地配置的 Provider，并安全显示密钥状态
`qllm_show_provider`	查看单个 Provider 的非敏感配置
`qllm_list_models`	查看本地配置或远程 `/models` 返回的模型
`qllm_route_task`	不花 token，根据任务类型选择 Provider / Model
`qllm_chat`	调用单个 Provider
`qllm_compare`	用同一个问题对比多个 Provider
`qllm_pipeline`	串联多个模型步骤完成任务
`qllm_heavy_discuss`	多视角、多模型讨论，可由模型或 Codex 主持
`qllm_heavy_render`	把 Codex 主持后的讨论渲染成 Markdown / HTML 报告
`qllm_claude_code_*`	通过 MCP 安全调用本机 Claude Code CLI

快速开始

1. 准备环境

要求：

macOS 或 Linux
Python 3.10+
一个支持 MCP 的客户端，例如 Codex、Claude Desktop、Claude Code、Cursor 等
至少一个 LLM Provider 的 API Key

克隆项目：

git clone https://github.com/joeseesun/qiaomu-llm-mcp.git
cd qiaomu-llm-mcp

如果你还没有 GitHub 版本，也可以先在本地目录安装：

cd /path/to/qiaomu-llm-mcp

2. 安装 Python 依赖

python3 -m venv .venv
.venv/bin/python -m pip install -U pip
.venv/bin/python -m pip install -e .

确认可执行文件存在：

test -x .venv/bin/qiaomu-llm-mcp && echo "qiaomu-llm-mcp installed"
.venv/bin/python -c "import qiaomu_llm_mcp; print(qiaomu_llm_mcp.__version__)"

MCP server 通常通过 stdio 被客户端启动。直接运行时它会等待 MCP 客户端消息，这是正常现象。

3. 创建 Provider 注册表

复制示例配置：

mkdir -p ~/.config/qiaomu-llm
cp examples/registry.example.json ~/.config/qiaomu-llm/registry.json

编辑 ~/.config/qiaomu-llm/registry.json，保留你要用的 Provider，删除不用的 Provider。

示例中的 Z.ai Coding Plan 使用专用 Coding endpoint：

{
  "base_url": "https://api.z.ai/api/coding/paas/v4",
  "default_model": "glm-5.2"
}

注意：Z.ai Coding Plan 要使用 https://api.z.ai/api/coding/paas/v4，不要误用通用 endpoint https://api.z.ai/api/paas/v4。

4. 把 API Key 放进 Keychain

推荐使用 Keychain，不要把明文 Key 写入配置文件。

Z.ai：

security add-generic-password -U \
  -s qiaomu-llm \
  -a zai-glm \
  -w "$ZAI_API_KEY"

DeepSeek：

security add-generic-password -U \
  -s qiaomu-llm \
  -a deepseek \
  -w "$DEEPSEEK_API_KEY"

Anthropic-compatible Provider：

security add-generic-password -U \
  -s qiaomu-llm \
  -a anthropic \
  -w "$ANTHROPIC_API_KEY"

注册表里对应写法：

{
  "secret_ref": "keychain:qiaomu-llm/zai-glm"
}

也支持环境变量：

{
  "secret_ref": "env:ZAI_API_KEY"
}

但公开仓库、团队配置和长期使用建议优先 Keychain。

接入 Codex

编辑 Codex 配置文件，例如 ~/.codex/config.toml：

[mcp_servers.qiaomu-llm]
command = "/absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp"

本机示例：

[mcp_servers.qiaomu-llm]
command = "/Users/joe/Documents/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp"

重启 Codex 后，应该可以看到 qllm_* 工具。

接入 Claude Desktop

编辑 Claude Desktop 的 MCP 配置：

{
  "mcpServers": {
    "qiaomu-llm": {
      "command": "/absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp"
    }
  }
}

重启客户端后，确认工具列表里出现 qllm_list_providers。

基础用法

查看 Provider

{
  "params": {
    "response_format": "markdown"
  }
}

调用工具：qllm_list_providers

调用 Z.ai Coding Plan

{
  "params": {
    "provider": "zai-glm",
    "model": "glm-5.2",
    "prompt": "Reply exactly: qiaomu-llm-mcp-ok",
    "thinking_type": "disabled",
    "max_tokens": 64
  }
}

调用工具：qllm_chat

对比多个模型

{
  "params": {
    "prompt": "用三条原则解释如何开始一个可持续的冥想习惯。",
    "task_type": "writing",
    "providers": ["zai-glm", "deepseek", "aigocode-anthropic"],
    "max_providers": 3,
    "response_format": "markdown"
  }
}

调用工具：qllm_compare

多步骤流水线

{
  "params": {
    "input": "写一个面向普通人的冥想 App 产品方向。",
    "steps": [
      {
        "name": "research",
        "task_type": "research",
        "instruction": "提出用户痛点、竞争差异和核心场景。"
      },
      {
        "name": "prd",
        "task_type": "writing",
        "instruction": "把上一步整理成结构化 PRD 摘要。"
      },
      {
        "name": "review",
        "task_type": "review",
        "instruction": "审查 PRD 摘要里的风险、遗漏和过度承诺。"
      }
    ],
    "response_format": "markdown"
  }
}

调用工具：qllm_pipeline

HeavySkill 式讨论

由 Codex 主持

适合当前 Codex 已经掌握工作区、文件、用户偏好和上下文的场景。

{
  "params": {
    "question": "一个普通人如何开始冥想，并长期坚持？",
    "mode": "deliberation",
    "k": 4,
    "host_mode": "codex",
    "write_report": true,
    "write_html": true
  }
}

调用工具：qllm_heavy_discuss

工具会返回：

多个模型的独立观点
host_prompt
可选的 Markdown / HTML 初始报告

把 host_prompt 交给 Codex 综合后，再调用 qllm_heavy_render 输出最终报告。

由模型主持

适合想让某个强模型直接完成主持总结的场景。

{
  "params": {
    "question": "如何设计一个隐私友好的冥想 App？",
    "mode": "deliberation",
    "k": 4,
    "providers": ["zai-glm", "deepseek", "aigocode-anthropic"],
    "host_mode": "model",
    "host_provider": "aigocode-anthropic",
    "rounds": 2,
    "write_report": true,
    "write_html": true
  }
}

Claude Code CLI 工具

如果本机安装了 Claude Code CLI，本项目还提供 qllm_claude_code_* 工具。

常见用途：

查看 Claude Code 能力：qllm_claude_code_capabilities
查看可用模型别名和本地最近使用模型：qllm_claude_code_models
非交互调用 Claude Code：qllm_claude_code_run
查看 Claude Code session：qllm_claude_code_sessions

示例：用 Sonnet 4.6 写一首诗。

{
  "params": {
    "cwd": "/Users/joe/Documents/智谱",
    "prompt": "请用中文写一首 12 行现代诗，只输出诗。",
    "model": "claude-sonnet-4-6",
    "tools": [],
    "user_facing": true,
    "timeout": 300
  }
}

默认不会暴露 --dangerously-skip-permissions。需要文件编辑时，请显式设置 allowed_tools，并限制 cwd。

安全与隐私边界

API Key 不应该写进 README、Prompt、Git 仓库或 MCP 请求参数。
推荐使用 keychain:<service>/<account>；工具只返回密钥状态，不返回明文。
Provider 错误信息会做敏感字段脱敏，但上游服务返回的文本仍应谨慎处理。
qllm_claude_code_run 是本机命令执行边界，默认只允许 Read，需要编辑或 Shell 时必须显式放开。
HeavySkill 报告可能包含你的问题、模型输出和上下文摘要。公开分享前请人工检查。
本项目不会提供云端代理服务，也不会替你保存 API Key。

故障排查

看不到 MCP 工具

确认 MCP 配置中的 command 是绝对路径：

ls -la /absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp

然后重启 MCP 客户端。

`Registry not found`

创建注册表：

mkdir -p ~/.config/qiaomu-llm
cp examples/registry.example.json ~/.config/qiaomu-llm/registry.json

或设置环境变量：

export QIAOMU_LLM_REGISTRY=/path/to/registry.json

`Missing Keychain secret`

检查服务名和账号是否一致：

security find-generic-password -s qiaomu-llm -a zai-glm -w

如果没有，重新写入：

security add-generic-password -U -s qiaomu-llm -a zai-glm -w "$ZAI_API_KEY"

Z.ai Coding Plan 请求失败

检查三件事：

base_url 是否是 https://api.z.ai/api/coding/paas/v4
model 是否是你的 Coding Plan 可用模型，例如 glm-5.2
Keychain 中的 zai-glm 是否写入了正确 API Key

模型列表为空

有些 Provider 的 /models endpoint 不可用，或账号不开放模型枚举。可以在 registry.json 里手动写 models 和 default_model。

本地验证

开发者可运行：

.venv/bin/python -m compileall src
.venv/bin/python -m pip install -e .

如果配置了真实 Provider，可在 MCP 客户端中运行：

{
  "params": {
    "provider": "zai-glm",
    "model": "glm-5.2",
    "prompt": "Reply exactly: ok",
    "max_tokens": 16
  }
}

路线图

可选 aisuite adapter：当目标 Provider 覆盖足够稳定时再加入，不影响 Z.ai Coding Plan 专用 endpoint。
更完整的安装 smoke test 脚本。
Provider preset 管理命令。
报告模板主题和更多 HTML 输出样式。
更细粒度的成本、token 和超时预算策略。

GitHub 发布

发布前的 GitHub About、topics、social preview 和验证清单见 docs/github-publish-checklist.md。

维护者

qiaomu.ai: https://qiaomu.ai
Blog: https://blog.qiaomu.ai
推荐看: https://tuijian.qiaomu.ai
X: https://x.com/vista8
GitHub: https://github.com/joeseesun/
微信公众号：向阳乔木推荐看

License

MIT License. See LICENSE.

English

qiaomu-llm-mcp is a local MCP gateway for people who use multiple LLM providers and want one safe tool surface for routing, comparison, pipelines, and multi-model deliberation.

It keeps provider metadata in ~/.config/qiaomu-llm/registry.json and recommends storing secrets in macOS Keychain. The MCP tools expose secret status, not raw API keys.

Why Use It

One MCP server for many providers.
Bring your own keys; no hosted proxy.
Route tasks before spending tokens.
Compare providers on the same prompt.
Chain models into practical pipelines.
Run HeavySkill-style discussions where multiple models produce independent views and Codex or a selected model hosts the synthesis.
Optionally call local Claude Code CLI through a controlled MCP wrapper.

Install

git clone https://github.com/joeseesun/qiaomu-llm-mcp.git
cd qiaomu-llm-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -U pip
.venv/bin/python -m pip install -e .

Configure Providers

mkdir -p ~/.config/qiaomu-llm
cp examples/registry.example.json ~/.config/qiaomu-llm/registry.json

Store secrets in Keychain:

security add-generic-password -U -s qiaomu-llm -a zai-glm -w "$ZAI_API_KEY"

For Z.ai Coding Plan, use the Coding endpoint:

https://api.z.ai/api/coding/paas/v4

not the general endpoint:

https://api.z.ai/api/paas/v4

Codex MCP Config

[mcp_servers.qiaomu-llm]
command = "/absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp"

Restart Codex and look for qllm_* tools.

Example Tools

qllm_list_providers: list configured providers and secret status.
qllm_chat: call one provider.
qllm_compare: compare several providers.
qllm_pipeline: run sequential model steps.
qllm_heavy_discuss: run multi-model deliberation.
qllm_heavy_render: render Codex-hosted synthesis to Markdown / HTML.
qllm_claude_code_run: run a bounded non-interactive Claude Code task.

Security Notes

Do not commit API keys.
Prefer Keychain refs such as keychain:qiaomu-llm/zai-glm.
Review generated HeavySkill reports before sharing them publicly.
Grant Claude Code file-editing or shell permissions only when the task needs them.

Verification

.venv/bin/python -m compileall src
.venv/bin/python -m pip install -e .

Then call qllm_list_providers from your MCP client.

Maintainer

Created and maintained by 向阳乔木.

X: https://x.com/vista8
GitHub: https://github.com/joeseesun/