{
"markdown": "\n# brainstorm-mcp\n\n[](https://www.npmjs.com/package/brainstorm-mcp)\n[](https://www.npmjs.com/package/brainstorm-mcp)\n[](https://github.com/spranab/brainstorm-mcp/blob/main/LICENSE)\n[](https://ideacred.com/profile/spranab)\n[](https://www.producthunt.com/products/brainstorm-3?launch=brainstorm-4)\n\nAsk one model a design question and you get one confident answer, with no\nsignal about which parts it is unsure of. Ask three and the disagreement is\nthe signal.\n\nbrainstorm-mcp runs multi-round debates between GPT, Gemini, DeepSeek, Claude\nand local Ollama models from inside your editor: they see and critique each\nother's answers across rounds, then you get a 3-bullet synthesis —\nrecommendation, key tradeoffs, strongest disagreement. Also does instant\nquick mode, multi-model code review with verdicts, and red-team/Socratic\nstyles. Hosted mode needs zero API keys.\n\n**Don't trust one AI. Make them argue.**\n\n
\n \n
\n\n### Demo\n\n[](https://youtu.be/L5kli5_fgkI)\n\n> Click to watch: 3 models debate, cross-examine, and produce a structured verdict — all inside Claude Code.\n\n## Features\n\n- **Hosted mode** — No API keys needed. Uses models in your environment (Claude Opus/Sonnet/Haiku) via sub-agents\n- **API mode** — Direct model API calls with parallel execution across OpenAI, Gemini, DeepSeek, Groq, Ollama\n- **CLI mode** — Debate through agent CLIs you already have (`claude`, `codex`, and more) so debates run on your **subscription instead of API credits**\n- **brainstorm_quick** — Instant multi-model perspectives in under 10 seconds\n- **brainstorm_review** — Multi-model code review with structured findings, severity ratings, and verdicts\n- **Debate styles** — Freeform, red-team (adversarial), and Socratic (probing questions)\n- **Context injection** — Ground debates in actual code, diffs, or architecture docs\n- **3-bullet synthesis verdicts** — Recommendation, Key Tradeoffs, Strongest Disagreement\n- **Claude as participant** — Claude debates alongside external models with full conversation context\n- **Multi-round debates** — Models see and critique each other's responses across rounds\n- **Parallel execution** — All models respond concurrently within each round\n- **Resilient** — One model failing doesn't abort the debate\n- **Cross-platform** — Works on macOS, Windows, and Linux\n\n## Install (60 seconds)\n\n```bash\nclaude mcp add brainstorm -- npx -y brainstorm-mcp\n```\n\nThat is enough for hosted mode (no API keys — it debates using the models\nalready available in your environment). Add provider keys to bring GPT,\nGemini, DeepSeek, Groq or Ollama into the debate.\n\n### Claude Code\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"brainstorm\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"brainstorm-mcp\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-...\",\n \"GEMINI_API_KEY\": \"AIza...\",\n \"DEEPSEEK_API_KEY\": \"sk-...\"\n }\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"brainstorm\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"brainstorm-mcp\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-...\",\n \"DEEPSEEK_API_KEY\": \"sk-...\"\n }\n }\n }\n}\n```\n\n### Manual Install\n\n```bash\nnpm install -g brainstorm-mcp\nbrainstorm-mcp\n```\n\n> **Hosted mode** requires no API keys — just install and go. The host (Claude Code) executes prompts using its own model access.\n\n## Configuration\n\n### Option 1: Environment Variables (simplest)\n\n```\nOPENAI_API_KEY=sk-...\nGEMINI_API_KEY=AIza...\nDEEPSEEK_API_KEY=sk-...\n```\n\n### Option 2: Config File (full control)\n\nSet `BRAINSTORM_CONFIG` to point to a JSON config:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"model\": \"gpt-5.4\", \"apiKeyEnv\": \"OPENAI_API_KEY\" },\n \"gemini\": { \"model\": \"gemini-2.5-flash\", \"apiKeyEnv\": \"GEMINI_API_KEY\" },\n \"deepseek\": { \"model\": \"deepseek-chat\", \"apiKeyEnv\": \"DEEPSEEK_API_KEY\" },\n \"ollama\": { \"model\": \"llama3.1\", \"baseURL\": \"http://localhost:11434/v1\" }\n }\n}\n```\n\nKnown providers (`openai`, `gemini`, `deepseek`, `groq`, `mistral`, `together`, `moonshot`,\n`minimax`, `glm`, `qwen`) don't need a `baseURL`.\n\nAny model id the provider serves works, including OpenAI's GPT-6 (`openai:gpt-6-astra`) and the\ngpt-5.x reasoning models: brainstorm picks the request shape each model expects and retries with\nthe other shape if the API rejects it.\n\n### Option 3: CLI Providers (use a subscription, not API credits)\n\nIf you already pay for Claude Code, Codex, Gemini CLI, and friends, brainstorm can shell out to\nthose CLIs instead of buying API credits. **Any agent CLI found on your `PATH` is registered\nautomatically at startup** — no configuration needed:\n\n```\n[brainstorm] Detected CLI provider(s) on PATH: claude, codex (subscription-based, no API cost)\n```\n\nUse them like any other provider:\n\n```json\n{ \"topic\": \"GraphQL vs REST\", \"models\": [\"claude:sonnet\", \"codex:default\", \"openai:gpt-5.4\"] }\n```\n\nBuilt-in adapters:\n\n| Provider | Command | Default model | Status |\n|----------|---------|---------------|--------|\n| `claude` | `claude -p` | `sonnet` | verified |\n| `codex` | `codex exec` | `default` | verified |\n| `gemini` | `gemini -p` | `gemini-2.5-pro` | best-effort, verify locally |\n| `cursor-agent` | `cursor-agent -p` | `default` | best-effort |\n| `opencode` | `opencode run` | `default` | best-effort |\n| `qwen` | `qwen -p` | `qwen3-coder-plus` | best-effort |\n| `kimi` | `kimi --print` | `default` | best-effort |\n| `droid` | `droid exec` | `default` | best-effort |\n\n`:default` means \"let the CLI use whatever model it's configured with\". CLI calls run\nwith tools disabled and a read-only sandbox where the CLI supports it — they generate text, they\ndon't touch your repo. Provider-specific API key env vars (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)\nare stripped from the child process so the CLI falls back to your subscription login.\n\nEnv knobs:\n\n| Variable | Effect |\n|----------|--------|\n| `BRAINSTORM_CLI_PROVIDERS` | `auto` (default), `off`, or a comma-separated list of adapters to detect |\n| `BRAINSTORM_PREFER_CLI` | `1` — debates with no explicit `models` use only CLI providers, skipping metered APIs |\n| `BRAINSTORM_CLI_TIMEOUT_MS` | Per-call timeout for CLI providers (default 300000) |\n\nTo pin a model or add a CLI that isn't built in, use the config file:\n\n```json\n{\n \"providers\": {\n \"claude\": { \"type\": \"cli\", \"model\": \"opus\" },\n \"my-cli\": {\n \"type\": \"cli\",\n \"adapter\": \"custom\",\n \"command\": \"some-agent-cli\",\n \"args\": [\"run\", \"--model\", \"{{model}}\", \"--quiet\", \"{{prompt}}\"],\n \"promptVia\": \"arg\",\n \"model\": \"some-model\"\n }\n }\n}\n```\n\nTemplate placeholders: `{{model}}`, `{{system}}`, `{{prompt}}`, `{{outfile}}`. A lone placeholder\nthat resolves to nothing drops out of the command line along with the flag introducing it, so\n`[\"--model\", \"{{model}}\"]` works even for `provider:default`. Set `\"promptVia\": \"stdin\"` to pipe\nthe prompt instead of passing it as an argument.\n\n#### Coding-plan backends through the Claude CLI\n\nMoonshot (Kimi), MiniMax, and Z.ai (GLM) sell coding-plan subscriptions that speak the Anthropic\nAPI. Point the `claude` binary at one of them and that vendor joins the debate on the plan you\nalready pay for:\n\n```json\n{\n \"providers\": {\n \"moonshot\": { \"type\": \"cli\", \"backend\": \"moonshot\", \"model\": \"kimi-k2-thinking\" },\n \"minimax\": { \"type\": \"cli\", \"backend\": \"minimax\", \"model\": \"MiniMax-M2\" },\n \"glm\": { \"type\": \"cli\", \"backend\": \"glm\", \"model\": \"glm-4.6\" }\n }\n}\n```\n\n| Backend | Endpoint | Token env var |\n|---------|----------|---------------|\n| `moonshot` | `https://api.moonshot.ai/anthropic` | `MOONSHOT_API_KEY` |\n| `minimax` | `https://api.minimax.io/anthropic` | `MINIMAX_API_KEY` |\n| `glm` | `https://api.z.ai/api/anthropic` | `ZAI_API_KEY` |\n\nThe token is read from your environment at call time — the config file holds the variable name,\nnever the secret. `ANTHROPIC_API_KEY` is stripped from the child so your Anthropic account is\nnever billed for these. Any CLI provider also accepts an `\"env\"` block to override the backend\nmanually; a value of `\"$NAME\"` indirects through the server's environment.\n\nThese vendors are reachable as plain metered APIs too — `moonshot`, `minimax`, `glm` and `qwen`\nhave known base URLs, so `MOONSHOT_API_KEY` alone is enough to register `moonshot` as an API\nprovider.\n\n## Tools\n\n| Tool | Description | Annotation |\n|------|-------------|------------|\n| `brainstorm` | Multi-round debate between AI models (API or hosted mode) | readOnly |\n| `brainstorm_quick` | Instant multi-model perspectives — parallel, no rounds | readOnly |\n| `brainstorm_review` | Multi-model code review with findings, severity, verdict | readOnly |\n| `brainstorm_respond` | Submit Claude's response in an interactive session | readOnly |\n| `brainstorm_collect` | Submit model responses in a hosted session | readOnly |\n| `list_providers` | Show configured providers, API key status, and detected CLIs | readOnly |\n| `add_provider` | Add a new API or CLI provider at runtime | non-destructive |\n\n## Usage Examples\n\n### Example 1: Quick Multi-Model Perspectives\n\n**Prompt:** \"Use brainstorm_quick to compare Redis vs PostgreSQL for session storage\"\n\n**Tool called:** `brainstorm_quick`\n```json\n{ \"topic\": \"Redis vs PostgreSQL for session storage in a Node.js app\" }\n```\n\n**Output:** Each configured model responds independently in parallel. You get a side-by-side comparison in under 10 seconds with model names, responses, timing, and cost.\n\n**Error handling:** If a model fails (rate limit, timeout), the tool continues with remaining models and shows which ones failed.\n\n---\n\n### Example 2: Multi-Model Code Review\n\n**Prompt:** \"Review this diff for security issues\" (with a git diff pasted)\n\n**Tool called:** `brainstorm_review`\n```json\n{\n \"diff\": \"diff --git a/src/auth.ts ...\",\n \"title\": \"Add JWT authentication middleware\",\n \"focus\": [\"security\", \"correctness\"]\n}\n```\n\n**Output:** A structured verdict (approve / approve with warnings / needs changes) with a findings table showing severity, category, file, line numbers, and suggestions. Includes model agreement analysis — issues flagged by multiple models have higher confidence.\n\n**Error handling:** If synthesis fails, raw model reviews are still returned.\n\n---\n\n### Example 3: Hosted Mode Brainstorm (No API Keys)\n\n**Prompt:** \"Brainstorm using opus, sonnet, and haiku about whether we should use GraphQL or REST\"\n\n**Tool called:** `brainstorm`\n```json\n{\n \"topic\": \"GraphQL vs REST for our public API\",\n \"models\": [\"opus\", \"sonnet\", \"haiku\"],\n \"mode\": \"hosted\",\n \"rounds\": 2,\n \"style\": \"redteam\"\n}\n```\n\n**Output:** The tool returns prompts for each model. The host (Claude Code) spawns sub-agents with different models, collects responses, and feeds them back via `brainstorm_collect`. After all rounds, a synthesis model produces a 3-bullet verdict: Recommendation, Key Tradeoffs, Strongest Disagreement.\n\n**Error handling:** Sessions expire after 10 minutes. If a session is not found, a clear error message is returned with instructions to start a new one.\n\n## How It Works\n\n### API / CLI Mode\n1. You ask Claude to brainstorm a topic\n2. The tool sends the topic to all configured providers in parallel — HTTP for API providers, a spawned subprocess for CLI providers\n3. Claude reads their responses and contributes its own perspective\n4. Models see each other's responses and refine across rounds\n5. A synthesizer produces the final verdict\n\n### Hosted Mode\n1. You ask Claude to brainstorm with specific models (e.g., opus, sonnet, haiku)\n2. The tool returns prompts — no API calls are made\n3. Claude spawns sub-agents with different models to execute prompts\n4. Responses are collected and fed back for the next round\n5. Repeat until synthesis\n\n## Privacy Policy\n\nbrainstorm-mcp runs entirely on your machine and does **not** collect, store, or transmit any personal data, telemetry, or analytics.\n\nIn **API mode**, prompts are sent directly from your machine to the model providers you configure (OpenAI, Gemini, DeepSeek, etc.) using your own API keys. In **CLI mode**, prompts are passed to agent CLIs installed on your machine, which talk to their own vendors under your existing subscription. In **hosted mode**, no external API calls are made.\n\nDebate sessions are stored in-memory only with a 10-minute TTL. No data is written to disk unless you explicitly save results.\n\nFull privacy policy: [PRIVACY.md](PRIVACY.md)\n\n## Support\n\n- **Issues**: https://github.com/spranab/brainstorm-mcp/issues\n- **Email**: developer@pranab.co.in\n- **Repository**: https://github.com/spranab/brainstorm-mcp\n\n## Development\n\n```bash\ngit clone https://github.com/spranab/brainstorm-mcp.git\ncd brainstorm-mcp\nnpm install\nnpm run build\nnpm start\n```\n\n## Related projects\n\nOther agent infrastructure by the same author, built to be used together:\n\n- [saga-mcp](https://github.com/spranab/saga-mcp) — SQLite-backed project\n tracker: once the debate settles, the decision goes somewhere durable.\n- [yantrikdb-mcp](https://github.com/yantrikos/yantrikdb-mcp) — persistent\n cognitive memory so the agent remembers what you decided and why.\n- [swarmcode](https://github.com/spranab/swarmcode) — real-time channel\n between Claude Code instances on different machines.\n- [truenas-mcp](https://github.com/spranab/truenas-mcp) — 278 TrueNAS SCALE\n actions behind one hierarchical tool.\n- [mcpier](https://github.com/spranab/mcpier) — self-hosted MCP control plane\n that keeps API keys off your clients.\n\n## License\n\nMIT\n",
"bytes": 14087,
"sha": "9e7e9bb3606db4f5766813d11bf9dcd3cc8699a200eddc44925bf8d585241814",
"repo_slug": "spranab/brainstorm-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_spranab_brainstorm_mcp_53a489de/readme"
}
![\"brainstorm-mcp](\"docs/hero.png\")
\n