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 客户端会看到这些工具：

Related MCP server: HydraMCP

推荐工作流

用户问题
  |
  +-- qllm_route_task 选择模型
  |
  +-- qllm_chat / qllm_compare / qllm_pipeline
  |
  +-- 复杂议题: qllm_heavy_discuss
        |
        +-- 多模型独立给观点
        +-- Codex 或指定模型主持
        +-- qllm_heavy_render 输出 Markdown / HTML

这套设计的核心不是“多叫几个模型凑热闹”，而是让不同模型承担不同角色：快速模型做初稿，强推理模型做审查，写作模型做表达，Codex 作为当前工作区里的主持人整合上下文和行动方案。

快速开始

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 请求失败

检查三件事：

1. base_url 是否是 https://api.z.ai/api/coding/paas/v4

2. model 是否是你的 Coding Plan 可用模型，例如 glm-5.2

3. 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。

维护者

Copyright (c) 向阳乔木

• 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/

MIT License. See LICENSE.