Skip to content
Back to search

mcp-rubber-duck

An MCP server that acts as a bridge to query multiple OpenAI-compatible LLMs with MCP tool access. Just like rubber duck debugging, explain your problems to various AI "ducks" who can actually research and get different perspectives!

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nesquikm/mcp-rubber-duck with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nesquikm/mcp-rubber-duck'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nesquikm--mcp-rubber-duck/badge.svg)](/listings/nesquikm--mcp-rubber-duck)

HTML

<a href="/listings/nesquikm--mcp-rubber-duck"><img src="/api/listings/nesquikm--mcp-rubber-duck/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 292 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP Rubber Duck
  2. 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!
  3. [![npm version](https://img.shields.io/npm/v/mcp-rubber-duck.svg)](https://www.npmjs.com/package/mcp-rubber-duck)
  4. [![Docker Image](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/nesquikm/mcp-rubber-duck/pkgs/container/mcp-rubber-duck)
  5. [![MCP Registry](https://img.shields.io/badge/MCP-Registry-green)](https://registry.modelcontextprotocol.io)
  6. <p align="center">
  7. <img src="assets/mcp-rubber-duck.jpg" alt="MCP Rubber Duck - AI ducks helping debug code" width="600">
  8. </p>
  9. > **Why direct provider integration?** MCP's `sampling` primitive -- a server borrowing the *host's* model -- was deprecated in the [2026-07-28 spec RC](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) in favor of servers integrating directly with LLM provider APIs. Rubber Duck has always worked this way (it brings its own ducks), so it's aligned with where the protocol is heading -- no migration required.
  10. ## Features
  11. - **Universal OpenAI Compatibility** -- Works with any OpenAI-compatible API endpoint
  12. - **CLI Agent Support** -- Use CLI coding agents (Claude Code, Codex, Gemini CLI, Grok, Aider) as ducks
  13. - **Multiple Ducks** -- Configure and query multiple LLM providers simultaneously
  14. - **Conversation Management** -- Maintain context across multiple messages
  15. - **Duck Council** -- Get responses from all your configured LLMs at once
  16. - **Consensus Voting** -- Multi-duck voting with reasoning and confidence scores
  17. - **LLM-as-Judge** -- Have ducks evaluate and rank each other's responses
  18. - **Iterative Refinement** -- Two ducks collaboratively improve responses
  19. - **Structured Debates** -- Oxford, Socratic, and adversarial debate formats
  20. - **MCP Prompts** -- 8 reusable prompt templates for multi-LLM workflows
  21. - **Vision Input** -- Send images alongside prompts to vision-capable models ([docs](./docs/tools.md#vision-input))
  22. - **Automatic Failover** -- Falls back to other providers if primary fails
  23. - **Health Monitoring** -- Real-time health checks for all providers
  24. - **Usage Tracking** -- Track requests, tokens, and estimated costs per provider
  25. - **MCP Bridge** -- Connect ducks to other MCP servers for extended functionality ([docs](./docs/mcp-bridge.md))
  26. - **Guardrails** -- Pluggable safety layer with rate limiting, token limits, pattern blocking, and PII redaction ([docs](./docs/guardrails.md))
  27. - **Granular Security** -- Per-server approval controls with session-based approvals
  28. - **Interactive UIs** -- Rich HTML panels for compare, vote, debate, and usage tools (via [MCP Apps](https://github.com/modelcontextprotocol/ext-apps))
  29. - **Tool Annotations** -- MCP-compliant hints for tool behavior (read-only, destructive, etc.)
  30. - **Structured Output** -- `outputSchema` on tools returning structured JSON for client-side validation (Cursor, VS Code/Copilot)
  31. - **Spec-Aligned by Design** -- connects directly to provider APIs, the path the MCP `2026-07-28` spec recommends now that server-side `sampling` is deprecated ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577))
  32. ## Supported Providers
  33. ### HTTP Providers (OpenAI-compatible API)
  34. Any provider with an OpenAI-compatible API endpoint, including:
  35. - **OpenAI**
  36. - **Google Gemini**
  37. - **Anthropic** (via OpenAI-compatible endpoints)
  38. - **Groq** (fast inference for open-weight models)
  39. - **Together AI** (broad open-weight model catalog)
  40. - **Perplexity** (online models with web search)
  41. - **Azure OpenAI**, **Ollama**, **LM Studio**, **Custom**
  42. ### CLI Providers (Coding Agents)
  43. Command-line coding agents that run as local processes:
  44. - **Claude Code** (`claude`) -- **Codex** (`codex`) -- **Gemini CLI** (`gemini`) -- **Grok CLI** (`grok`) -- **Aider** (`aider`) -- **Custom**
  45. See [CLI Providers](./docs/cli-providers.md) for full setup and configuration.
  46. ## Quick Start
  47. ```bash
  48. # Install globally
  49. npm install -g mcp-rubber-duck
  50. # Or use npx directly in Claude Desktop config
  51. npx mcp-rubber-duck
  52. ```
  53. **Using Claude Desktop?** Jump to [Claude Desktop Configuration](./docs/claude-desktop.md).
  54. **Using Cursor, VS Code, Windsurf, or another tool?** See the [Setup Guide](./docs/setup.md).
  55. ## Installation
  56. ### Prerequisites
  57. - Node.js 20 or higher
  58. - npm or yarn
  59. - At least one API key for an HTTP provider, **or** a CLI coding agent installed locally
  60. ### Install from NPM
  61. ```bash
  62. npm install -g mcp-rubber-duck
  63. ```
  64. ### Install from Source
  65. ```bash
  66. git clone https://github.com/nesquikm/mcp-rubber-duck.git
  67. cd mcp-rubber-duck
  68. npm install
  69. npm run build
  70. npm start
  71. ```
  72. ## Configuration
  73. Create a `.env` file or `config/config.json`. Key environment variables:
  74. | Variable | Description |
  75. |----------|-------------|
  76. | `OPENAI_API_KEY` | OpenAI API key |
  77. | `GEMINI_API_KEY` | Google Gemini API key |
  78. | `GROQ_API_KEY` | Groq API key |
  79. | `OPENAI_DEFAULT_MODEL` | OpenAI model (default: `gpt-5.4`) |
  80. | `GEMINI_DEFAULT_MODEL` | Gemini model (default: `gemini-3.8-flash`) |
  81. | `GROQ_DEFAULT_MODEL` | Groq model (default: `openai/gpt-oss-120b`) |
  82. | `DEFAULT_PROVIDER` | Default provider key: `openai`, `google`, `groq`, `ollama`, or a custom name |
  83. | `DEFAULT_TEMPERATURE` | Default temperature (e.g., `0.7`) |
  84. | `LOG_LEVEL` | `debug`, `info`, `warn`, `error` |
  85. | `MCP_SERVER` | Set to `true` for MCP server mode |
  86. | `MCP_BRIDGE_ENABLED` | Enable MCP Bridge (ducks access external MCP servers) |
  87. | `CUSTOM_{NAME}_*` | Custom HTTP providers |
  88. | `CLI_{AGENT}_ENABLED` | Enable CLI agents (`CLAUDE`, `CODEX`, `GEMINI`, `GROK`, `AIDER`) |
  89. Full reference: **[Configuration docs](./docs/configuration.md)**
  90. ## Interactive UIs (MCP Apps)
  91. 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.
  92. ### Compare Ducks
  93. Compare multiple model responses side-by-side, with latency indicators, token counts, model badges, and error states.
  94. <p align="center">
  95. <img src="assets/ext-apps-compare.png" alt="Compare Ducks interactive UI" width="600">
  96. </p>
  97. ### Duck Vote
  98. Have multiple ducks vote on options, displayed as a visual vote tally with bar charts, consensus badge, winner card, confidence bars, and collapsible reasoning.
  99. <p align="center">
  100. <img src="assets/ext-apps-vote.png" alt="Duck Vote interactive UI" width="600">
  101. </p>
  102. ### Duck Debate
  103. Structured multi-round debate between ducks, shown as a round-by-round view with format badge, participant list, collapsible rounds, and synthesis section.
  104. <p align="center">
  105. <img src="assets/ext-apps-debate.png" alt="Duck Debate interactive UI" width="600">
  106. </p>
  107. ### Usage Stats
  108. Usage analytics with summary cards, provider breakdown with expandable rows, token distribution bars, and estimated costs.
  109. <p align="center">
  110. <img src="assets/ext-apps-usage-stats.png" alt="Usage Stats interactive UI" width="600">
  111. </p>
  112. ## Available Tools
  113. | Tool | Description |
  114. |------|-------------|
  115. | `ask_duck` | Ask a single question to a specific LLM provider |
  116. | `chat_with_duck` | Conversation with context maintained across messages |
  117. | `clear_conversations` | Clear all conversation history |
  118. | `list_ducks` | List configured providers and health status |
  119. | `list_models` | List available models for providers |
  120. | `compare_ducks` | Ask the same question to multiple providers simultaneously |
  121. | `duck_council` | Get responses from all configured ducks |
  122. | `get_usage_stats` | Usage statistics and estimated costs |
  123. | `duck_vote` | Multi-duck voting with reasoning and confidence |
  124. | `duck_judge` | Have one duck evaluate and rank others' responses |
  125. | `duck_iterate` | Iteratively refine a response between two ducks |
  126. | `duck_debate` | Structured multi-round debate between ducks |
  127. | `mcp_status` | MCP Bridge status and connected servers |
  128. | `get_pending_approvals` | Pending MCP tool approval requests |
  129. | `approve_mcp_request` | Approve or deny a duck's MCP tool request |
  130. Full reference with input schemas: **[Tools docs](./docs/tools.md)**
  131. ## Available Prompts
  132. | Prompt | Purpose | Required Arguments |
  133. |--------|---------|-------------------|
  134. | `perspectives` | Multi-angle analysis with assigned lenses | `problem`, `perspectives` |
  135. | `assumptions` | Surface hidden assumptions in plans | `plan` |
  136. | `blindspots` | Hunt for overlooked risks and gaps | `proposal` |
  137. | `tradeoffs` | Structured option comparison | `options`, `criteria` |
  138. | `red_team` | Security/risk analysis from multiple angles | `target` |
  139. | `reframe` | Problem reframing at different levels | `problem` |
  140. | `architecture` | Design review across concerns | `design`, `workloads`, `priorities` |
  141. | `diverge_converge` | Divergent exploration then convergence | `challenge` |
  142. Full reference with examples: **[Prompts docs](./docs/prompts.md)**
  143. ## Development
  144. ```bash
  145. npm run dev # Development with watch mode
  146. npm test # Run all tests
  147. npm run lint # ESLint
  148. npm run typecheck # Type check without emit
  149. ```
  150. ## [Documentation](./docs/README.md)
  151. | Topic | Link |
  152. |-------|------|
  153. | **Setup guide (all tools)** | **[docs/setup.md](./docs/setup.md)** |
  154. | Full configuration reference | [docs/configuration.md](./docs/configuration.md) |
  155. | Claude Desktop setup | [docs/claude-desktop.md](./docs/claude-desktop.md) |
  156. | All tools with schemas | [docs/tools.md](./docs/tools.md) |
  157. | Prompt templates | [docs/prompts.md](./docs/prompts.md) |
  158. | CLI coding agents | [docs/cli-providers.md](./docs/cli-providers.md) |
  159. | MCP Bridge | [docs/mcp-bridge.md](./docs/mcp-bridge.md) |
  160. | Guardrails | [docs/guardrails.md](./docs/guardrails.md) |
  161. | Docker deployment | [docs/docker.md](./docs/docker.md) |
  162. | Provider-specific setup | [docs/provider-setup.md](./docs/provider-setup.md) |
  163. | Usage examples | [docs/usage-examples.md](./docs/usage-examples.md) |
  164. | Architecture | [docs/architecture.md](./docs/architecture.md) |
  165. | Roadmap | [docs/roadmap.md](./docs/roadmap.md) |
  166. ## Troubleshooting
  167. ### Provider Not Working
  168. 1. Check API key is correctly set
  169. 2. Verify endpoint URL is correct
  170. 3. Run health check: `list_ducks({ check_health: true })`
  171. 4. Check logs for detailed error messages
  172. ### OpenAI gpt-5.6 / gpt-6 Models Fail With the MCP Bridge
  173. OpenAI's Chat Completions API rejects function tools for the gpt-5.6 and gpt-6 families (`400 Function tools with reasoning_effort are not supported ... use /v1/responses`). They work for plain calls, but with `MCP_BRIDGE_ENABLED=true` the ducks attach tools and those requests fail. Use `gpt-5.4` (the default) or `gpt-5.4-mini` until Responses API support lands ([#166](https://github.com/nesquikm/mcp-rubber-duck/issues/166)).
  174. ### Connection Issues
  175. - For local providers (Ollama, LM Studio), ensure they're running
  176. - Check firewall settings for local endpoints
  177. - Verify network connectivity to cloud providers
  178. ### Rate Limiting
  179. - Configure failover to alternate providers
  180. - Adjust `max_retries` and `timeout` settings
  181. - See [Guardrails](./docs/guardrails.md) for rate limiting configuration
  182. ## Contributing
  183. ```
  184. __
  185. <(o )___
  186. ( ._> /
  187. `---' Quack! Ready to debug!
  188. ```
  189. 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.
  190. Check out our [Contributing Guide](./CONTRIBUTING.md) to get started.
  191. **Quick start for contributors:**
  192. 1. Fork the repository
  193. 2. Create a feature branch
  194. 3. Follow our [conventional commit guidelines](./CONTRIBUTING.md#commit-messages-duck-communication-protocol)
  195. 4. Add tests for new functionality
  196. 5. Submit a pull request
  197. ## License
  198. MIT License - see LICENSE file for details
  199. ## Acknowledgments
  200. - Inspired by the rubber duck debugging method
  201. - Built on the Model Context Protocol (MCP)
  202. - Uses OpenAI SDK for HTTP provider compatibility
  203. - Supports CLI coding agents (Claude Code, Codex, Gemini CLI, Grok, Aider)
  204. ## Changelog
  205. See [CHANGELOG.md](./CHANGELOG.md) for a detailed history of changes and releases.
  206. ## Registry & Directory
  207. - **NPM Package**: [npmjs.com/package/mcp-rubber-duck](https://www.npmjs.com/package/mcp-rubber-duck)
  208. - **Docker Images**: [ghcr.io/nesquikm/mcp-rubber-duck](https://github.com/nesquikm/mcp-rubber-duck/pkgs/container/mcp-rubber-duck)
  209. - **MCP Registry**: Official MCP server `io.github.nesquikm/rubber-duck`
  210. - **Glama Directory**: [glama.ai/mcp/servers/@nesquikm/mcp-rubber-duck](https://glama.ai/mcp/servers/@nesquikm/mcp-rubber-duck)
  211. - **Awesome MCP Servers**: Listed in the [community directory](https://github.com/punkpeye/awesome-mcp-servers)
  212. ## Support
  213. - Report issues: https://github.com/nesquikm/mcp-rubber-duck/issues
  214. - Documentation: https://github.com/nesquikm/mcp-rubber-duck/wiki
  215. - Discussions: https://github.com/nesquikm/mcp-rubber-duck/discussions
  216. ---
  217. Happy Debugging with your AI Duck Panel!

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.