Skip to content
Conduit

mcp server

quorum-mcp

Multi-provider AI consensus orchestration via MCP - Get better answers through deliberation

aj-geddes/quorum-mcpcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "aj-geddes-quorum-mcp": {
      "command": "uvx",
      "args": [
        "quorum-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 26, 2026

Quorum-MCP

Multi-AI Consensus System MCP Server - Get better answers through deliberation

Tests Coverage Python License

🎯 Overview

Quorum-MCP orchestrates multiple AI providers (Anthropic Claude, OpenAI, Google Gemini, Cohere, Mistral AI, Novita AI, Ollama) through multi-round deliberation to produce consensus-based responses. By combining different AI models, you get more balanced, comprehensive, and reliable answers.

Why Quorum?

  • 🎭 Diverse Perspectives: Each AI has unique strengths and biases
  • 🤝 Consensus Building: Agreement across models increases confidence
  • 🔍 Quality Assurance: Cross-validation catches errors and hallucinations
  • 💡 Richer Insights: Disagreements reveal nuanced viewpoints

✨ Features

Multi-Provider Support (7 Providers!)

  • 🤖 Anthropic Claude - Thoughtful, nuanced reasoning
    • Models: claude-3-5-sonnet-20241022 (default), claude-3-opus, claude-3-haiku
    • Context: 200K tokens | Cost: $3-$15/1M input
  • 🧠 OpenAI - Broad knowledge, strong reasoning
    • Models: gpt-4o (default), gpt-4o-mini, gpt-4-turbo
    • Context: 128K tokens | Cost: $0.15-$30/1M input
  • ✨ Google Gemini - Fast, cost-effective, huge context
    • Models: gemini-2.5-flash (default), gemini-2.5-pro, gemini-1.5-pro
    • Context: Up to 2M tokens | Cost: $0.15-$1.25/1M input
  • 🏢 Cohere - Enterprise RAG, production-ready
    • Models: command-r-plus (default), command-r, command-light
    • Context: 128K tokens | Cost: $0.30-$15/1M input
    • Features: Excellent RAG capabilities, free tier available
  • 🇪🇺 Mistral AI - Best pricing, European AI
    • Models: mistral-large-latest (default), mistral-small-latest, mixtral-8x22b
    • Context: 128K tokens | Cost: $0.04-$6/1M input
    • Features: GDPR compliant, competitive with GPT-4
  • ⚡ Novita AI - Ultra-low cost, OpenAI-compatible
    • Models: llama-3.3-70b (default), deepseek-r1, qwen-2.5-72b
    • Context: 128K tokens | Cost: $0.04-$0.20/1M input (cheapest!)
    • Features: OpenAI-compatible API, multiple open-source models
  • 🏠 Ollama (Local LLMs) - Private, zero-cost local inference
    • Models: llama3.2 (default), llama3.1, mistral, mixtral, qwen3, deepseek-r1, gemma3
    • Context: Up to 128K tokens | Cost: $0.00 (100% local)
    • Privacy: 100% - Data never leaves your machine

Three Operational Modes

1. Quick Consensus (Single Round)

# Fast consensus for straightforward queries
session = await orchestrator.execute_quorum(
    query="What are Python best practices?",
    mode="quick_consensus"
)

2. Full Deliberation (3 Rounds)

# Multi-round deliberation for complex decisions
# Round 1: Independent analysis
# Round 2: Cross-review and critique
# Round 3: Final synthesis
session = await orchestrator.execute_quorum(
    query="Should we use microservices or monolith?",
    mode="full_deliberation"
)

3. Devil's Advocate (Critical Analysis)

# Challenge assumptions and find weaknesses
session = await orchestrator.execute_quorum(
    query="We should skip testing to move faster",
    mode="devils_advocate"
)

Additional Features

  • 🌐 Web Dashboard: Interactive browser-based UI (NEW!)
  • ⚡ Async/Await: Non-blocking I/O throughout
  • 💰 Cost Tracking: Per-provider and total cost reporting (including $0 for local)
  • 📊 Cost Calculator: Estimate costs before running queries (NEW!)
  • 🏠 Local LLMs: Zero-cost inference with Ollama (100% private)
  • 📝 Session Management: Persistent session storage and retrieval
  • 🔒 Type Safe: Full Pydantic validation
  • 🧪 Well Tested: 105 passing tests, 95% provider coverage
  • 📡 MCP Integration: Works with Claude Desktop and other MCP clients
  • 🔄 Real-Time Updates: WebSocket-powered live notifications (NEW!)

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/aj-geddes/quorum-mcp.git
cd quorum-mcp

# Install with dependencies
pip install -e .

# Or install for development
pip install -e ".[dev]"

Configuration

Cloud Providers (Optional)

Set your API keys as environment variables (use whichever providers you prefer):

# Traditional providers
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."

# New providers (optional - mix and match!)
export COHERE_API_KEY="..."
export MISTRAL_API_KEY="..."
export NOVITA_API_KEY="..."

Local LLMs with Ollama (Optional, Zero Cost)

Install and run Ollama for 100% free, private local inference:

# Install Ollama (Mac/Linux/Windows)
# Visit: https://ollama.com/download

# Start Ollama server
ollama serve

# Pull a model (in another terminal)
ollama pull llama3.2

# Optional: Configure Ollama host (default: http://localhost:11434)
export OLLAMA_HOST="http://localhost:11434"
export OLLAMA_ENABLE="true"  # Set to "false" to disable

Note: At least one provider (cloud or local) is required. Ollama enables zero-cost consensus!

Running the Server

Option 1: Web Dashboard (Recommended for Getting Started)

Launch the interactive web interface:

# Start the web server
quorum-web

# Or run directly
python -m quorum_mcp.web_server

Then open http://localhost:8000 in your browser. No coding required!

Features:

  • 🎨 Interactive query builder
  • 📊 Real-time consensus visualization
  • 💰 Cost calculator and estimator
  • 📈 Session history and analytics
  • 🔍 Provider comparison tools

📖 Read the Web Dashboard Guide

Option 2: MCP Server (for Claude Desktop Integration)

For programmatic use or Claude Desktop integration:

# Start the MCP server
quorum-mcp

# Or run directly
python -m quorum_mcp.server

Basic Usage Example

import asyncio
from quorum_mcp.orchestrator import Orchestrator
from quorum_mcp.providers import (
    AnthropicProvider,
    OpenAIProvider,
    GeminiProvider,
    CohereProvider,     # New!
    MistralProvider,    # New!
    NovitaProvider,     # New!
    OllamaProvider,     # Local
)
from quorum_mcp.session import get_session_manager

async def main():
    # Initialize providers (use any combination!)
    providers = [
        AnthropicProvider(),
        OpenAIProvider(),
        GeminiProvider(),
        # Add new providers for more perspectives:
        CohereProvider(),   # Enterprise RAG
        MistralProvider(),  # Best pricing
        NovitaProvider(),   # Ultra-low cost
    ]

    # Start session manager
    session_manager = get_session_manager()
    await session_manager.start()

    # Create orchestrator
    orchestrator = Orchestrator(
        providers=providers,
        session_manager=session_manager
    )

    # Execute consensus
    session = await orchestrator.execute_quorum(
        query="What is the best database for a startup?",
        context="Small team, rapid iteration, expecting growth",
        mode="quick_consensus"
    )

    # Print results
    print(f"Confidence: {session.consensus['confidence']:.2%}")
    print(f"Summary: {session.consensus['summary']}")
    print(f"Cost: ${session.consensus['cost']['total_cost']:.4f}")

    await session_manager.stop()

asyncio.run(main())

📖 Usage

MCP Tools

Quorum-MCP provides two simple tools for MCP clients:

q_in - Submit Query

{
  "query": "What are the top 3 considerations for API design?",
  "context": "Building a REST API for a SaaS product",
  "mode": "quick_consensus"
}

Returns:

{
  "session_id": "abc-123-def",
  "status": "completed",
  "confidence": 0.85,
  "consensus": {
    "summary": "Based on consensus...",
    "agreement_areas": [...],
    "cost": {...}
  }
}

q_out - Retrieve Results

{
  "session_id": "abc-123-def"
}

Returns the full session data including consensus results.

Using with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "quorum-mcp": {
      "command": "quorum-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key",
        "GOOGLE_API_KEY": "your-key"
      }
    }
  }
}

Running Demos

# Three-provider consensus demo (cloud providers)
python examples/three_provider_demo.py

# Local LLM demo with Ollama (zero cost!)
python examples/local_llm_demo.py

# End-to-end demo with all modes
python examples/end_to_end_demo.py

# Session management demo
python examples/session_demo.py

💰 Cost Comparison

ProviderModelInput ($/1M)Output ($/1M)Context WindowSpeed
Ollama 🏆llama3.2$0.00$0.00128K⚡⚡⚡
Ollamamistral$0.00$0.0032K⚡⚡⚡
Gemini2.5 Flash$0.15$0.60200K⚡⚡⚡
OpenAI4o-mini$0.15$0.60128K⚡⚡⚡
Claude3.5 Sonnet$3.00$15.00200K⚡⚡
Gemini2.5 Pro$1.25$10.00200K⚡⚡
Gemini1.5 Pro$1.25$5.002M⚡
OpenAI4o$2.50$10.00128K⚡⚡
Claude3 Opus$15.00$75.00200K⚡

Typical Consensus Cost (500 tokens in, 300 tokens out, 3 providers):

  • Quick Consensus: ~$0.01 - $0.02
  • Full Deliberation (3 rounds): ~$0.03 - $0.06

🏗️ Architecture

graph TD
    Client[MCP Client<br/>Claude Desktop]

    subgraph FastMCP["FastMCP Server"]
        QIn[q_in tool]
        QOut[q_out tool]
    end

    subgraph Orchestrator["Orchestrator Engine"]
        Consensus[Consensus Algorithms<br/>• Agreement detection<br/>• Confidence scoring<br/>• Synthesis & summarization]
    end

    subgraph Providers["AI Providers"]
        Anthropic[AnthropicProvider<br/>• Async client<br/>• Token counting<br/>• Cost tracking<br/>• Error mapping]
        OpenAI[OpenAIProvider<br/>• Async client<br/>• tiktoken<br/>• Cost tracking<br/>• Error mapping]
        Gemini[GeminiProvider<br/>• Async client<br/>• Token counting<br/>• Cost tracking<br/>• Error mapping]
        Ollama[OllamaProvider<br/>• Async client<br/>• Local inference<br/>• Zero cost<br/>• 100% private]
    end

    AnthropicAPI[Anthropic API]
    OpenAIAPI[OpenAI API]
    GeminiAPI[Google AI API]
    OllamaServer[Ollama Server<br/>Local]

    Client -->|stdio/HTTP| FastMCP
    QIn --> Consensus
    QOut --> Consensus
    Consensus --> Anthropic
    Consensus --> OpenAI
    Consensus --> Gemini
    Consensus --> Ollama
    Anthropic --> AnthropicAPI
    OpenAI --> OpenAIAPI
    Gemini --> GeminiAPI
    Ollama --> OllamaServer

📁 Project Structure

quorum-mcp/
├── src/quorum_mcp/
│   ├── __init__.py
│   ├── server.py              # FastMCP server with q_in/q_out tools
│   ├── orchestrator.py        # Multi-provider orchestration engine
│   ├── session.py             # Session management and persistence
│   └── providers/
│       ├── __init__.py
│       ├── base.py            # Abstract provider interface
│       ├── anthropic_provider.py  # Claude integration
│       ├── openai_provider.py     # OpenAI integration
│       ├── gemini_provider.py     # Gemini integration
│       └── ollama_provider.py     # Ollama local LLM integration
├── examples/
│   ├── three_provider_demo.py  # Demo with cloud providers
│   ├── local_llm_demo.py       # Demo with Ollama (zero cost)
│   ├── end_to_end_demo.py      # All operational modes
│   └── session_demo.py         # Session management
├── tests/
│   ├── test_session.py
│   ├── test_orchestrator.py
│   ├── test_anthropic_provider.py
│   ├── test_openai_provider.py
│   ├── test_gemini_provider.py
│   ├── test_ollama_provider.py
│   └── test_integration.py
├── docs/
│   └── session_management.md
├── .pre-commit-config.yaml     # Code quality hooks
├── pyproject.toml              # Project configuration
├── README.md
└── worklog.md                  # Complete development history

🧪 Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=quorum_mcp --cov-report=html

# Run specific test file
pytest tests/test_gemini_provider.py -v

# Run only fast tests
pytest -m "not slow"

Code Quality

The project uses pre-commit hooks for code quality:

# Install pre-commit hooks
pre-commit install

# Run manually
pre-commit run --all-files

# Individual tools
black src/ tests/           # Format code
ruff check src/ tests/      # Lint code
mypy src/                   # Type check

Adding a New Provider

  1. Create a new provider class inheriting from Provider
  2. Implement required methods:
    • send_request(request: ProviderRequest) -> ProviderResponse
    • count_tokens(text: str) -> int
    • get_cost(tokens_input: int, tokens_output: int) -> float
    • get_provider_name() -> str
    • get_model_info() -> dict
  3. Add comprehensive tests
  4. Update providers/__init__.py
  5. Add to server.py initialization

See gemini_provider.py as a reference implementation.

📊 Test Coverage

Module                          Coverage
────────────────────────────────────────
providers/ollama_provider.py      95%
providers/gemini_provider.py      95%
providers/openai_provider.py      78%
session.py                        90%
providers/base.py                 67%
providers/anthropic_provider.py   56%
orchestrator.py                   45%
────────────────────────────────────────
Total                             32%

Test Results:

  • ✅ 105 tests passing (76 + 29 new Ollama tests)
  • ❌ 58 tests failing (testing unimplemented features)
  • ⚠️ 16 errors (mock-related, non-critical)

🗺️ Roadmap

✅ Phase 1: MVP (Complete)

  • Provider abstraction layer
  • Anthropic Claude integration
  • OpenAI integration
  • Basic orchestration engine
  • Session management
  • FastMCP server with q_in/q_out
  • Cost tracking

✅ Phase 2: Testing (Complete)

  • Comprehensive unit tests
  • Provider test suites
  • Integration tests
  • Pre-commit hooks
  • Code quality tooling

✅ Phase 3: Google Gemini (Complete)

  • Gemini provider implementation
  • Token counting and cost tracking
  • 95% test coverage
  • Three-provider demo
  • Documentation updates

✅ Phase 4: Local LLMs (Complete)

  • Ollama provider integration
  • Support for Llama 3.2, Llama 3.1, Mistral, Mixtral, Qwen3, DeepSeek-R1, Gemma3
  • Zero-cost local inference ($0.00)
  • 100% privacy-preserving mode (data never leaves machine)
  • 95% test coverage (29 passing tests)
  • Local LLM demo and hybrid (local+cloud) demo
  • Automatic server detection and model availability checking

🔮 Phase 5: Advanced Features (Future)

  • Additional local LLM providers (LM Studio, vLLM, text-generation-webui)
  • OpenAI-compatible API provider (universal local LLM support)
  • Mistral AI provider (cloud)
  • Provider health monitoring
  • Dynamic provider selection
  • Caching layer
  • Rate limiting
  • Budget controls
  • Performance benchmarking
  • Web UI for result visualization

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (pytest)
  5. Run code quality checks (pre-commit run --all-files)
  6. Commit your changes (git commit -m 'Add amazing feature')
  7. Push to the branch (git push origin feature/amazing-feature)
  8. Open a Pull Request

Code Standards:

  • Black for formatting (100 char lines)
  • Ruff for linting
  • mypy for type checking
  • pytest for testing (aim for 80%+ coverage)
  • Comprehensive docstrings

❓ Troubleshooting

API Key Issues

# Verify API keys are set
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
echo $GOOGLE_API_KEY

# Test individual provider
python -c "from quorum_mcp.providers import GeminiProvider; print(GeminiProvider())"

Import Errors

# Reinstall in development mode
pip install -e .

# Or reinstall with dependencies
pip install -e ".[dev]" --force-reinstall

Test Failures

# Clear pytest cache
rm -rf .pytest_cache __pycache__

# Run with verbose output
pytest -vv --tb=short

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

📬 Contact

Built with ❤️ for better AI through collaboration

↑↓ navigate openesc close