mcp-rubber-duck

# MCP Rubber Duck An MCP (Model Context Protocol) server that acts as a bridge to query multiple LLMs -- both OpenAI-compatible HTTP APIs and CLI coding agents. Just like rubber duck debugging, explain your problems to various AI "ducks" and get different perspectives! [](https://www.npmjs.com/package/mcp-rubber-duck) [](https://github.com/nesquikm/mcp-rubber-duck/pkgs/container/mcp-rubber-duck) [](https://registry.modelcontextprotocol.io) <p align="center"> <img src="assets/mcp-rubber-duck.jpg" alt="MCP Rubber Duck - AI ducks helping debug code" width="600"> </p> ## Features - **Universal OpenAI Compatibility** -- Works with any OpenAI-compatible API endpoint - **CLI Agent Support** -- Use CLI coding agents (Claude Code, Codex, Gemini CLI, Grok, Aider) as ducks - **Multiple Ducks** -- Configure and query multiple LLM providers simultaneously - **Conversation Management** -- Maintain context across multiple messages - **Duck Council** -- Get responses from all your configured LLMs at once - **Consensus Voting** -- Multi-duck voting with reasoning and confidence scores - **LLM-as-Judge** -- Have ducks evaluate and rank each other's responses - **Iterative Refinement** -- Two ducks collaboratively improve responses - **Structured Debates** -- Oxford, Socratic, and adversarial debate formats - **MCP Prompts** -- 8 reusable prompt templates for multi-LLM workflows - **Vision Input** -- Send images alongside prompts to vision-capable models ([docs](./docs/tools.md#vision-input)) - **Automatic Failover** -- Falls back to other providers if primary fails - **Health Monitoring** -- Real-time health checks for all providers - **Usage Tracking** -- Track requests, tokens, and estimated costs per provider - **MCP Bridge** -- Connect ducks to other MCP servers for extended functionality ([docs](./docs/mcp-bridge.md)) - **Guardrails** -- Pluggable safety layer with rate limiting, token limits, pattern blocking, and PII redaction ([docs](./docs/guardrails.md)) - **Granular Security** -- Per-server approval controls with session-based approvals - **Interactive UIs** -- Rich HTML panels for compare, vote, debate, and usage tools (via [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)) - **Tool Annotations** -- MCP-compliant hints for tool behavior (read-only, destructive, etc.) - **Structured Output** -- `outputSchema` on tools returning structured JSON for client-side validation (Cursor, VS Code/Copilot) ## Supported Providers ### HTTP Providers (OpenAI-compatible API) Any provider with an OpenAI-compatible API endpoint, including: - **OpenAI** (GPT-5.1, o3, o4-mini) - **Google Gemini** (Gemini 3, Gemini 2.5 Pro/Flash) - **Anthropic** (via OpenAI-compatible endpoints) - **Groq** (Llama 4, Llama 3.3) - **Together AI** (Llama 4, Qwen, and more) - **Perplexity** (Online models with web search) - **Anyscale**, **Azure OpenAI**, **Ollama**, **LM Studio**, **Custom** ### CLI Providers (Coding Agents) Command-line coding agents that run as local processes: - **Claude Code** (`claude`) -- **Codex** (`codex`) -- **Gemini CLI** (`gemini`) -- **Grok CLI** (`grok`) -- **Aider** (`aider`) -- **Custom** See [CLI Providers](./docs/cli-providers.md) for full setup and configuration. ## Quick Start ```bash # Install globally npm install -g mcp-rubber-duck # Or use npx directly in Claude Desktop config npx mcp-rubber-duck ``` **Using Claude Desktop?** Jump to [Claude Desktop Configuration](./docs/claude-desktop.md). **Using Cursor, VS Code, Windsurf, or another tool?** See the [Setup Guide](./docs/setup.md). ## Installation ### Prerequisites - Node.js 20 or higher - npm or yarn - At least one API key for an HTTP provider, **or** a CLI coding agent installed locally ### Install from NPM ```bash npm install -g mcp-rubber-duck ``` ### Install from Source ```bash git clone https://github.com/nesquikm/mcp-rubber-duck.git cd mcp-rubber-duck npm install npm run build npm start ``` ## Configuration Create a `.env` file or `config/config.json`. Key environment variables: | Variable | Description | |----------|-------------| | `OPENAI_API_KEY` | OpenAI API key | | `GEMINI_API_KEY` | Google Gemini API key | | `GROQ_API_KEY` | Groq API key | | `DEFAULT_PROVIDER` | Default provider (e.g., `openai`) | | `DEFAULT_TEMPERATURE` | Default temperature (e.g., `0.7`) | | `LOG_LEVEL` | `debug`, `info`, `warn`, `error` | | `MCP_SERVER` | Set to `true` for MCP server mode | | `MCP_BRIDGE_ENABLED` | Enable MCP Bridge (ducks access external MCP servers) | | `CUSTOM_{NAME}_*` | Custom HTTP providers | | `CLI_{AGENT}_ENABLED` | Enable CLI agents (`CLAUDE`, `CODEX`, `GEMINI`, `GROK`, `AIDER`) | Full reference: **[Configuration docs](./docs/configuration.md)** ## Interactive UIs (MCP Apps) Four tools -- `compare_ducks`, `duck_vote`, `duck_debate`, and `get_usage_stats` -- can render rich interactive HTML panels inside supported MCP clients via [MCP Apps](https://github.com/modelcontextprotocol/ext-apps). Once this MCP server is configured in a supporting client, the UIs appear automatically -- no additional setup is required. Clients without MCP Apps support still receive the same plain text output (no functionality is lost). See the [MCP Apps repo](https://github.com/modelcontextprotocol/ext-apps) for an up-to-date list of supported clients. ### Compare Ducks Compare multiple model responses side-by-side, with latency indicators, token counts, model badges, and error states. <p align="center"> <img src="assets/ext-apps-compare.png" alt="Compare Ducks interactive UI" width="600"> </p> ### Duck Vote Have multiple ducks vote on options, displayed as a visual vote tally with bar charts, consensus badge, winner card, confidence bars, and collapsible reasoning. <p align="center"> <img src="assets/ext-apps-vote.png" alt="Duck Vote interactive UI" width="600"> </p> ### Duck Debate Structured multi-round debate between ducks, shown as a round-by-round view with format badge, participant list, collapsible rounds, and synthesis section. <p align="center"> <img src="assets/ext-apps-debate.png" alt="Duck Debate interactive UI" width="600"> </p> ### Usage Stats Usage analytics with summary cards, provider breakdown with expandable rows, token distribution bars, and estimated costs. <p align="center"> <img src="assets/ext-apps-usage-stats.png" alt="Usage Stats interactive UI" width="600"> </p> ## Available Tools | Tool | Description | |------|-------------| | `ask_duck` | Ask a single question to a specific LLM provider | | `chat_with_duck` | Conversation with context maintained across messages | | `clear_conversations` | Clear all conversation history | | `list_ducks` | List configured providers and health status | | `list_models` | List available models for providers | | `compare_ducks` | Ask the same question to multiple providers simultaneously | | `duck_council` | Get responses from all configured ducks | | `get_usage_stats` | Usage statistics and estimated costs | | `duck_vote` | Multi-duck voting with reasoning and confidence | | `duck_judge` | Have one duck evaluate and rank others' responses | | `duck_iterate` | Iteratively refine a response between two ducks | | `duck_debate` | Structured multi-round debate between ducks | | `mcp_status` | MCP Bridge status and connected servers | | `get_pending_approvals` | Pending MCP tool approval requests | | `approve_mcp_request` | Approve or deny a duck's MCP tool request | Full reference with input schemas: **[Tools docs](./docs/tools.md)** ## Available Prompts | Prompt | Purpose | Required Arguments | |--------|---------|-------------------| | `perspectives` | Multi-angle analysis with assigned lenses | `problem`, `perspectives` | | `assumptions` | Surface hidden assumptions in plans | `plan` | | `blindspots` | Hunt for overlooked risks and gaps | `proposal` | | `tradeoffs` | Structured option comparison | `options`, `criteria` | | `red_team` | Security/risk analysis from multiple angles | `target` | | `reframe` | Problem reframing at different levels | `problem` | | `architecture` | Design review across concerns | `design`, `workloads`, `priorities` | | `diverge_converge` | Divergent exploration then convergence | `challenge` | Full reference with examples: **[Prompts docs](./docs/prompts.md)** ## Development ```bash npm run dev # Development with watch mode npm test # Run all tests npm run lint # ESLint npm run typecheck # Type check without emit ``` ## [Documentation](./docs/README.md) | Topic | Link | |-------|------| | **Setup guide (all tools)** | **[docs/setup.md](./docs/setup.md)** | | Full configuration reference | [docs/configuration.md](./docs/configuration.md) | | Claude Desktop setup | [docs/claude-desktop.md](./docs/claude-desktop.md) | | All tools with schemas | [docs/tools.md](./docs/tools.md) | | Prompt templates | [docs/prompts.md](./docs/prompts.md) | | CLI coding agents | [docs/cli-providers.md](./docs/cli-providers.md) | | MCP Bridge | [docs/mcp-bridge.md](./docs/mcp-bridge.md) | | Guardrails | [docs/guardrails.md](./docs/guardrails.md) | | Docker deployment | [docs/docker.md](./docs/docker.md) | | Provider-specific setup | [docs/provider-setup.md](./docs/provider-setup.md) | | Usage examples | [docs/usage-examples.md](./docs/usage-examples.md) | | Architecture | [docs/architecture.md](./docs/architecture.md) | | Roadmap | [docs/roadmap.md](./docs/roadmap.md) | ## Troubleshooting ### Provider Not Working 1. Check API key is correctly set 2. Verify endpoint URL is correct 3. Run health check: `list_ducks({ check_health: true })` 4. Check logs for detailed error messages ### Connection Issues - For local providers (Ollama, LM Studio), ensure they're running - Check firewall settings for local endpoints - Verify network connectivity to cloud providers ### Rate Limiting - Configure failover to alternate providers - Adjust `max_retries` and `timeout` settings - See [Guardrails](./docs/guardrails.md) for rate limiting configuration ## Contributing ``` __ <(o )___ ( ._> / `---' Quack! Ready to debug! ``` We love contributions! Whether you're fixing bugs, adding features, or teaching our ducks new tricks, we'd love to have you join the flock. Check out our [Contributing Guide](./CONTRIBUTING.md) to get started. **Quick start for contributors:** 1. Fork the repository 2. Create a feature branch 3. Follow our [conventional commit guidelines](./CONTRIBUTING.md#commit-messages-duck-communication-protocol) 4. Add tests for new functionality 5. Submit a pull request ## License MIT License - see LICENSE file for details ## Acknowledgments - Inspired by the rubber duck debugging method - Built on the Model Context Protocol (MCP) - Uses OpenAI SDK for HTTP provider compatibility - Supports CLI coding agents (Claude Code, Codex, Gemini CLI, Grok, Aider) ## Changelog See [CHANGELOG.md](./CHANGELOG.md) for a detailed history of changes and releases. ## Registry & Directory - **NPM Package**: [npmjs.com/package/mcp-rubber-duck](https://www.npmjs.com/package/mcp-rubber-duck) - **Docker Images**: [ghcr.io/nesquikm/mcp-rubber-duck](https://github.com/nesquikm/mcp-rubber-duck/pkgs/container/mcp-rubber-duck) - **MCP Registry**: Official MCP server `io.github.nesquikm/rubber-duck` - **Glama Directory**: [glama.ai/mcp/servers/@nesquikm/mcp-rubber-duck](https://glama.ai/mcp/servers/@nesquikm/mcp-rubber-duck) - **Awesome MCP Servers**: Listed in the [community directory](https://github.com/punkpeye/awesome-mcp-servers) ## Support - Report issues: https://github.com/nesquikm/mcp-rubber-duck/issues - Documentation: https://github.com/nesquikm/mcp-rubber-duck/wiki - Discussions: https://github.com/nesquikm/mcp-rubber-duck/discussions --- Happy Debugging with your AI Duck Panel!