# Setup Guide
<p align="center">
<img src="../assets/docs-setup.jpg" alt="Setup desk - pick your tool" width="600">
</p>
Add mcp-rubber-duck to your AI coding tool. Pick your tool below, copy the config, and you're done.
## Install
Choose one:
```bash
# Option A: Global install (recommended)
npm install -g mcp-rubber-duck
# Option B: No install needed — use npx in your config (see templates below)
```
## Choose Your Tool
- [Claude Desktop](#claude-desktop)
- [Claude Code](#claude-code)
- [Cursor](#cursor)
- [Windsurf](#windsurf)
- [VS Code](#vs-code)
- [Continue](#continue)
- [ChatGPT](#chatgpt)
---
## Claude Desktop
**Config file:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"rubber-duck": {
"command": "npx",
"args": ["-y", "mcp-rubber-duck"],
"env": {
"MCP_SERVER": "true",
"OPENAI_API_KEY": "sk-your-key-here",
"DEFAULT_PROVIDER": "openai"
}
}
}
}
```
If installed globally, replace `"command": "npx"` and `"args"` with just `"command": "mcp-rubber-duck"`.
**After editing:** Fully quit Claude Desktop (Cmd+Q / Alt+F4) and relaunch.
See also: [Claude Desktop detailed guide](./claude-desktop.md)
---
## Claude Code
**Preferred method** — use the CLI:
```bash
claude mcp add --scope user rubber-duck -- npx -y mcp-rubber-duck
```
Then edit `~/.claude.json` to add env vars to the entry that was just created:
```json
{
"mcpServers": {
"rubber-duck": {
"command": "npx",
"args": ["-y", "mcp-rubber-duck"],
"env": {
"MCP_SERVER": "true",
"OPENAI_API_KEY": "sk-your-key-here",
"DEFAULT_PROVIDER": "openai"
}
}
}
}
```
For **project scope** (shared with your team), use `--scope project` which writes to `.mcp.json` at the project root. Avoid committing API keys — use shell environment variables instead.
**After editing:** Start a new Claude Code session.
---
## Cursor
**Config file:**
- Project scope: `.cursor/mcp.json` (in project root)
- Global scope: `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"rubber-duck": {
"command": "npx",
"args": ["-y", "mcp-rubber-duck"],
"env": {
"MCP_SERVER": "true",
"OPENAI_API_KEY": "sk-your-key-here",
"DEFAULT_PROVIDER": "openai"
}
}
}
}
```
**After editing:** Reload window (Cmd+Shift+P → "Reload Window").
---
## Windsurf
**Config file:** `~/.codeium/windsurf/mcp_config.json`
Windsurf supports `${env:VAR_NAME}` syntax — set keys in your shell profile instead of hardcoding them:
```json
{
"mcpServers": {
"rubber-duck": {
"command": "npx",
"args": ["-y", "mcp-rubber-duck"],
"env": {
"MCP_SERVER": "true",
"OPENAI_API_KEY": "${env:OPENAI_API_KEY}",
"DEFAULT_PROVIDER": "openai"
}
}
}
}
```
Then add to your `~/.zshrc` or `~/.bashrc`:
```bash
export OPENAI_API_KEY="sk-your-key-here"
```
**After editing:** Reload window or restart Windsurf.
---
## VS Code
**Config file:** `.vscode/mcp.json` (in project root)
> **Important:** VS Code uses `"servers"`, not `"mcpServers"`.
VS Code also supports `${env:VAR_NAME}` syntax:
```json
{
"servers": {
"rubber-duck": {
"command": "npx",
"args": ["-y", "mcp-rubber-duck"],
"env": {
"MCP_SERVER": "true",
"OPENAI_API_KEY": "${env:OPENAI_API_KEY}",
"DEFAULT_PROVIDER": "openai"
}
}
}
}
```
Requires the GitHub Copilot extension with agent mode enabled.
**After editing:** Reload window (Cmd+Shift+P → "Reload Window").
---
## Continue
**Config file:** `.continue/config.yaml` (project or `~/.continue/config.yaml` for global)
> **Note:** Continue uses YAML, and `mcpServers` is an **array** (not an object).
```yaml
mcpServers:
- name: rubber-duck
command: npx
args:
- "-y"
- mcp-rubber-duck
env:
MCP_SERVER: "true"
OPENAI_API_KEY: sk-your-key-here
DEFAULT_PROVIDER: openai
```
**After editing:** Reload the Continue extension.
---
## ChatGPT
ChatGPT doesn't use a config file. Add MCP servers through the UI:
1. Open ChatGPT settings
2. Enable Developer Mode
3. Click "Add MCP Server"
4. Enter the server details
---
## Adding More Providers
Add any of these to the `env` block in your config:
```json
"GEMINI_API_KEY": "your-gemini-key",
"GROQ_API_KEY": "gsk_your-groq-key",
"OLLAMA_BASE_URL": "http://localhost:11434/v1",
"CLI_CLAUDE_ENABLED": "true",
"CLI_CODEX_ENABLED": "true"
```
See [Configuration](./configuration.md) for the full reference and [Provider Setup](./provider-setup.md) for per-provider instructions.
---
## Verify It Works
After restarting your tool, test the connection:
1. Ask your AI to use the `list_ducks` tool with `check_health: true`
2. You should see your configured providers listed as healthy
3. Try `ask_duck` with a simple prompt to confirm responses work
---
## Troubleshooting
| Problem | Fix |
|---------|-----|
| Server doesn't appear / no tools | Add `"MCP_SERVER": "true"` to the env block |
| "command not found" | Install globally (`npm i -g mcp-rubber-duck`) or use the npx config |
| 401 / API key error | Check key format (OpenAI: `sk-...`, Groq: `gsk_...`) |
| JSON parse error | Validate JSON — no trailing commas, use double quotes |
| VS Code: tools don't appear | Use `"servers"` key, not `"mcpServers"` |
| Changes not taking effect | Fully restart the tool (quit + relaunch for desktop apps) |
See [Claude Desktop troubleshooting](./claude-desktop.md#troubleshooting) for more details.
