# Second Opinion MCP

Get second opinions from multiple AI models while using Claude. Break the single-model echo chamber by consulting DeepSeek Reasoner, Kimi K2.5 (Moonshot), and 300+ OpenRouter models.

## What It Does

When working with Claude Code or Claude Desktop, this MCP server lets you:

- Get alternative perspectives on code, architecture, and decisions
- Run systematic code reviews with severity-classified issues
- Stage multi-model debates where AI models argue opposing positions
- Challenge proposals with anti-sycophancy mode (finds weaknesses, not validation)

## Quickstart

### 1. Install

```bash
pipx install second-opinion-mcp
```

If you don't have pipx, install it first: `pip install pipx && pipx ensurepath`

### 2. Setup

Run the interactive setup wizard:

```bash
second-opinion-mcp setup
```

The wizard will guide you through selecting providers and entering API keys. Keys are stored securely in your system's credential manager.

### 3. Register

After setup, copy the registration command from the wizard output, e.g.:

```bash
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek,moonshot" -- second-opinion-mcp
```

That's it. Restart Claude Code and the tools are available.

## Supported Models

### DeepSeek V3.2 (Recommended)

Chain-of-thought reasoning model. Best for code reviews and complex analysis.

- Get your API key at https://platform.deepseek.com
- Pricing: ~$0.28/$0.42 per million tokens (input/output)

### Kimi K2.5 (Moonshot)

Chinese AI model with thinking mode. Good for alternative perspectives and debates.

- Get your API key at https://platform.moonshot.cn
- Supports 256K context window

### OpenRouter (Optional)

Access 300+ models through a single API. Enable for variety or specific model access.

- Get your API key at https://openrouter.ai/keys

## Available Tools

### second_opinion

Get a straightforward second opinion on any question, code, or decision.

```
Use second_opinion to review this database schema: [paste schema]
```

### challenge

Anti-sycophancy mode. The model is instructed to find weaknesses, not validate.

```
Use challenge to critique: "We should use a global singleton for database connections"
```

### code_review

Systematic directory-based code review with BLOCKER/CRITICAL/MAJOR/MINOR classifications.

```
Use code_review on directory="./src" with focus_areas=["security", "performance"]
```

### consensus

Multi-model debate where DeepSeek and Moonshot argue opposing positions, then synthesize.

```
Use consensus to debate: "GraphQL vs REST for internal microservices"
```

### review_synthesis

Full workflow: parallel reviews from both models, debate, then synthesis instructions.

```
Perform a comprehensive code review of ./myproject using review_synthesis
```

## Usage Examples

### Thorough Code Review Workflow

For comprehensive code reviews, use this prompt pattern with Claude Code:

```
MyProject: perform a comprehensive deep parallel code review with deepseek and kimi
using mcp server second-opinion - save resulting md files to the project folder
to the docs subfolder in md format.

After that perform Consensus debate + arbiter synthesis using same mcp server tools
with opus 4.5 compiling a final document for the final review.

First 2 tasks can be run in parallel.
```

This triggers parallel code_review calls to DeepSeek and Moonshot, then a consensus debate on findings, and finally Claude synthesizes the final review document.

### Quick Second Opinion

```
Use second_opinion to review this database schema:
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255),
  password VARCHAR(255)
);
```

### Critical Challenge

```
Use challenge to critique this proposal: "We should use a global singleton for
database connections because it's simpler"
```

### Consensus Debate

```
Use consensus to debate: "GraphQL vs REST for our internal microservices API"
```

### Code Review with Focus Areas

```
Use code_review on directory="./src" with focus_areas=["security", "error-handling"]
and save_to="./docs/reviews"
```

## Configuration

### Changing Providers

After initial setup, reconfigure providers:

```bash
second-opinion-mcp setup
```

Or manually set the environment variable:

```bash
# Claude Code CLI
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek" -- second-opinion-mcp

# Only DeepSeek
export SECOND_OPINION_PROVIDERS="deepseek"

# Only Moonshot
export SECOND_OPINION_PROVIDERS="moonshot"

# All providers
export SECOND_OPINION_PROVIDERS="deepseek,moonshot,openrouter"
```

### API Key Management

Keys are stored in your system's credential manager (Windows Credential Manager, macOS Keychain, or Linux Secret Service).

To update keys:

```bash
second-opinion-mcp setup
```

Or manually set each provider's key:

```bash
# DeepSeek (key starts with sk-)
python3 -c "import keyring; keyring.set_password('second-opinion', 'deepseek', 'sk-YOUR_DEEPSEEK_KEY')"

# Moonshot/Kimi
python3 -c "import keyring; keyring.set_password('second-opinion', 'moonshot', 'YOUR_MOONSHOT_KEY')"

# OpenRouter (key starts with sk-or-)
python3 -c "import keyring; keyring.set_password('second-opinion', 'openrouter', 'sk-or-YOUR_OPENROUTER_KEY')"
```

Verify keys are configured:

```bash
python3 -c "import keyring; print('deepseek:', bool(keyring.get_password('second-opinion', 'deepseek'))); print('moonshot:', bool(keyring.get_password('second-opinion', 'moonshot'))); print('openrouter:', bool(keyring.get_password('second-opinion', 'openrouter')))"
```

### Claude Desktop Configuration

For Claude Desktop (the standalone app), add to `claude_desktop_config.json`:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "second-opinion": {
      "command": "second-opinion-mcp",
      "env": {
        "SECOND_OPINION_PROVIDERS": "deepseek,moonshot"
      }
    }
  }
}
```

## Troubleshooting

### "No API key configured" Error

Run the setup wizard again:

```bash
second-opinion-mcp setup
```

### "Keyring access failed" (Linux)

Linux without a desktop environment needs a keyring backend configured:

```bash
pip install keyrings.alt
mkdir -p ~/.local/share/python_keyring
echo -e "[backend]\ndefault-keyring=keyrings.alt.file.EncryptedKeyring" > ~/.local/share/python_keyring/keyringrc.cfg
```

### Connection Timeout

Check firewall, VPN, or proxy settings. Both DeepSeek (api.deepseek.com) and Moonshot (api.moonshot.ai) must be accessible.

### Rate Limit Exceeded

Moonshot has rate limits (3 concurrent, 20 RPM at Tier 0). Wait a minute and retry, or use fast mode for non-critical queries.

### Tool Not Found in Claude

Verify registration:

```bash
claude mcp list
```

If not listed, re-register:

```bash
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek,moonshot" -- second-opinion-mcp
```

## Advanced Usage

### Fast Mode

Skip the thinking/reasoning phase for quicker responses:

```
Use second_opinion with fast=true to check: is this regex correct?
```

Note: Code reviews always use full thinking mode regardless of this setting.

### Include Reasoning

See the model's chain-of-thought:

```
Use second_opinion with include_reasoning=true to analyze this algorithm
```

### Focus Areas for Reviews

```
Use code_review with focus_areas=["security", "error-handling", "performance"]
```

### Save Review Output

```
Use code_review on directory="./src" with save_to="./docs/reviews"
```

## Updating

The server checks for updates on startup and notifies you if a new version is available.

To update manually:

```bash
pipx upgrade second-opinion-mcp
```

Or reinstall:

```bash
pipx uninstall second-opinion-mcp
pipx install second-opinion-mcp
```

Your API keys are preserved in the system keyring across updates.

## Uninstalling

```bash
# Remove from Claude
claude mcp remove second-opinion

# Uninstall package
pipx uninstall second-opinion-mcp

# Optional: remove stored API keys
python3 -c "import keyring; keyring.delete_password('second-opinion', 'deepseek')"
python3 -c "import keyring; keyring.delete_password('second-opinion', 'moonshot')"
python3 -c "import keyring; keyring.delete_password('second-opinion', 'openrouter')"
```

## Security

API keys are stored in your OS keyring, not in environment variables or config files. The code review tool:

- Skips `.env` files, credentials, SSH keys, and certificates
- Validates directories against allowed roots
- Detects symlinks to prevent traversal attacks
- Limits content size to prevent memory exhaustion

## Cost Estimates

Per operation (typical usage):

| Tool | Approximate Cost |
|------|------------------|
| second_opinion / challenge | ~$0.001 |
| code_review | ~$0.01-0.05 |
| consensus (2 rounds) | ~$0.004-0.010 |
| review_synthesis | ~$0.02-0.10 |

## License

MIT License. See LICENSE file.

## Links

- [GitHub Repository](https://github.com/MarvinFS/second-opinion-mcp)
- [Issue Tracker](https://github.com/MarvinFS/second-opinion-mcp/issues)
- [Changelog](https://github.com/MarvinFS/second-opinion-mcp/blob/main/docs/CHANGELOG.md)
