qiaomu-llm-mcp

# Tool List > A local MCP gateway that turns many LLM providers, API keys, routing rules, and multi-model discussions into one tool surface. Suitable for these scenarios: - You use multiple LLM providers, such as Z.ai Coding Plan, DeepSeek, OpenAI-compatible API, Anthropic-compatible API, and Claude Code CLI. - You don't want to hardcode API keys into prompts, scripts, or Codex configurations. - You want to use a single set of tools for single-model calls, multi-model comparisons, pipelines, and HeavySkill-style multi-round discussions. - You need to let the strongest master model host discussions, rather than leaving all judgment to a single provider. This project is a local-first tool, with a provider registry stored in `~/.config/qiaomu-llm/registry.json` and secrets stored in macOS Keychain by default. The MCP server only exposes secret existence, not raw keys. ## What You Can Get After installation, MCP clients will see these tools: | Tool | Function | | --- | --- | | `qllm_list_providers` | List local providers and display secret status | | `qllm_show_provider` | View non-sensitive configuration of a single provider | | `qllm_list_models` | View local or remote `/models` returned models | | `qllm_route_task` | Choose a provider/model without spending tokens | | `qllm_chat` | Call a single provider | | `qllm_compare` | Compare multiple providers with the same prompt | | `qllm_pipeline` | Complete tasks with multiple model steps | | `qllm_heavy_discuss` | Multi-perspective, multi-model discussion, hosted by a model or Codex | | `qllm_heavy_render` | Render discussions into Markdown/HTML reports | | `qllm_claude_code_*` | Securely call local Claude Code CLI | ## Recommended Workflow ```text User question | +-- qllm_route_task chooses model | +-- qllm_chat / qllm_compare / qllm_pipeline | +-- Complex issues: qllm_heavy_discuss | +-- Multi-model independent views +-- Codex or specified model hosts +-- qllm_heavy_render outputs Markdown/HTML ``` This design focuses on letting different models take on different roles: fast models for drafts, strong reasoning models for review, writing models for expression, and Codex as the host in the current workspace. ## Quick Start ### 1. Prepare Environment Requirements: - macOS or Linux - Python 3.10+ - An MCP-compatible client, such as Codex, Claude Desktop, Claude Code, or Cursor - At least one LLM provider API key Clone the project: ```bash git clone https://github.com/joeseesun/qiaomu-llm-mcp.git cd qiaomu-llm-mcp ``` If you don't have a GitHub version, install locally: ```bash cd /path/to/qiaomu-llm-mcp ``` ### 2. Install Python Dependencies ```bash python3 -m venv .venv .venv/bin/python -m pip install -U pip .venv/bin/python -m pip install -e . ``` Confirm the executable exists: ```bash 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__)" ``` The MCP server usually runs through stdio launched by the client. It waits for MCP client messages when run directly. ### 3. Create Provider Registry Copy the example configuration: ```bash mkdir -p ~/.config/qiaomu-llm cp examples/registry.example.json ~/.config/qiaomu-llm/registry.json ``` Edit `~/.config/qiaomu-llm/registry.json`, keeping the providers you want and removing unused ones. ### 4. Store API Keys in Keychain Recommended to use Keychain, not plaintext keys in configurations. ## Integrate with Codex Edit Codex configuration file, e.g., `~/.codex/config.toml`: ```toml [mcp_servers.qiaomu-llm] command = "/absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp" ``` Local example: ```toml [mcp_servers.qiaomu-llm] command = "/Users/joe/Documents/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp" ``` Restart Codex to see `qllm_*` tools. ## Integrate with Claude Desktop Edit Claude Desktop's MCP configuration: ```json { "mcpServers": { "qiaomu-llm": { "command": "/absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp" } } } ``` Restart the client to see `qllm_list_providers`. ## Basic Usage ### View Providers ```json { "params": { "response_format": "markdown" } } ``` Call tool: `qllm_list_providers` ### Call Z.ai Coding Plan ```json { "params": { "provider": "zai-glm", "model": "glm-5.2", "prompt": "Reply exactly: qiaomu-llm-mcp-ok", "thinking_type": "disabled", "max_tokens": 64 } } ``` Call tool: `qllm_chat` ### Compare Multiple Models ```json { "params": { "prompt": "Explain how to start a sustainable meditation habit with three principles.", "task_type": "writing", "providers": ["zai-glm", "deepseek", "aigocode-anthropic"], "max_providers": 3, "response_format": "markdown" } } ``` Call tool: `qllm_compare` ### Multi-Step Pipeline ```json { "params": { "input": "Write a meditation app product direction for ordinary people.", "steps": [ { "name": "research", "task_type": "research", "instruction": "Propose user pain points, competitive differences, and core scenarios." }, { "name": "prd", "task_type": "writing", "instruction": "Organize the previous step into a structured PRD summary." }, { "name": "review", "task_type": "review", "instruction": "Review PRD summary for risks, omissions, and overcommitments." } ], "response_format": "markdown" } } ``` Call tool: `qllm_pipeline` ## HeavySkill-Style Discussion ### Hosted by Codex Suitable for scenarios where Codex has mastered the workspace, files, user preferences, and context. ```json { "params": { "question": "How can an ordinary person start meditating and persist?", "mode": "deliberation", "k": 4, "host_mode": "codex", "write_report": true, "write_html": true } } ``` Call tool: `qllm_heavy_discuss` The tool returns: - Independent views from multiple models - `host_prompt` - Optional Markdown/HTML initial report Pass `host_prompt` to Codex for synthesis, then call `qllm_heavy_render` to output the final report. ### Hosted by Model Suitable for scenarios where a strong model directly hosts and summarizes. ```json { "params": { "question": "How to design a privacy-friendly meditation 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 Tools If Claude Code CLI is installed locally, this project provides `qllm_claude_code_*` tools. Common uses: - View Claude Code capabilities: `qllm_claude_code_capabilities` - View available model aliases and recent usage: `qllm_claude_code_models` - Non-interactive call Claude Code: `qllm_claude_code_run` - View Claude Code sessions: `qllm_claude_code_sessions` Example: Write a poem with Sonnet 4.6. ```json { "params": { "cwd": "/Users/joe/Documents/智谱", "prompt": "Please write a 12-line modern poem in Chinese, only output the poem.", "model": "claude-sonnet-4-6", "tools": [], "user_facing": true, "timeout": 300 } } ``` ## Security and Privacy Boundaries - API keys should not be written into README, prompts, Git repositories, or MCP request parameters. - Recommended to use `keychain:<service>/<account>`; tools only return secret status, not raw keys. - Provider error messages are desensitized, but upstream service text should be handled with caution. - `qllm_claude_code_run` is a local command execution boundary, defaulting to only allow `Read`, requiring explicit permission for editing or shell usage. - HeavySkill reports may contain questions, model outputs, and context summaries. Please manually check before public sharing. - This project does not provide cloud proxy services or store API keys. ## Troubleshooting ### Can't See MCP Tools Confirm the `command` in MCP configuration is an absolute path: ```bash ls -la /absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp ``` Restart the MCP client. ### `Registry not found` Create the registry: ```bash mkdir -p ~/.config/qiaomu-llm cp examples/registry.example.json ~/.config/qiaomu-llm/registry.json ``` Or set the environment variable: ```bash export QIAOMU_LLM_REGISTRY=/path/to/registry.json ``` ### `Missing Keychain secret` Check service name and account consistency: ```bash security find-generic-password -s qiaomu-llm -a zai-glm -w ``` If not found, rewrite: ```bash security add-generic-password -U -s qiaomu-llm -a zai-glm -w "$ZAI_API_KEY" ``` ### Z.ai Coding Plan Request Failed Check three things: 1. Is `base_url` `https://api.z.ai/api/coding/paas/v4`? 2. Is `model` a usable model for your Coding Plan, e.g., `glm-5.2`? 3. Does Keychain `zai-glm` have the correct API key? ### Empty Model List Some providers' `/models` endpoint may not be available or accounts may not allow model enumeration. You can manually write `models` and `default_model` in `registry.json`. ## Local Verification Developers can run: ```bash .venv/bin/python -m compileall src .venv/bin/python -m pip install -e . ``` If a real provider is configured, run in the MCP client: ```json { "params": { "provider": "zai-glm", "model": "glm-5.2", "prompt": "Reply exactly: ok", "max_tokens": 16 } } ``` ## Roadmap - Optional `aisuite` adapter: add when target provider coverage is stable, without affecting Z.ai Coding Plan's dedicated endpoint. - More complete installation smoke test scripts. - Provider preset management commands. - Report template themes and more HTML output styles. - Finer-grained cost, token, and timeout budget strategies. ## GitHub Release Pre-release GitHub About, topics, social preview, and verification checklist see [docs/github-publish-checklist.md](docs/github-publish-checklist.md). ## Maintainer Copyright (c) 向阳乔木 - qiaomu.ai: https://qiaomu.ai - Blog: https://blog.qiaomu.ai - Recommended: https://tuijian.qiaomu.ai - X: https://x.com/vista8 - GitHub: https://github.com/joeseesun/ - WeChat Official Account: 向阳乔木推荐看 ## License MIT License. See [LICENSE](LICENSE). <a name="english"></a> # 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 ```bash 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 ```bash mkdir -p ~/.config/qiaomu-llm cp examples/registry.example.json ~/.config/qiaomu-llm/registry.json ``` Store secrets in Keychain: ```bash security add-generic-password -U -s qiaomu-llm -a zai-glm -w "$ZAI_API_KEY" ``` For Z.ai Coding Plan, use the Coding endpoint: ```text https://api.z.ai/api/coding/paas/v4 ``` not the general endpoint: ```text https://api.z.ai/api/paas/v4 ``` ## Codex MCP Config ```toml [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 ```bash .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 joeseesun. - X: https://x.com/vista8 - GitHub: https://github.com/joeseesun/ MIT License. See [LICENSE](LICENSE).