Geepers MCP

Model Context Protocol (MCP) servers for multi-agent orchestration. Run parallel research agents across academic, news, code, and financial sources, then synthesize findings into PDF, DOCX, or Markdown reports.

Author: Luke Steuber

• dr.eamer.dev
• @lukesteuber.com

Depends on geepers-kernel for LLM providers, orchestration, and data clients.

---

Quick Start

pip install geepers-mcp[all]

Add at least one API key to .env:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
XAI_API_KEY=xai-...

MCP tools become available in Claude Code right away:

Research quantum computing breakthroughs in 2025 using Beltalowda orchestration

---

How it works

Six MCP servers expose 32+ tools. The orchestration layer coordinates them:

Claude Code Client
       |  MCP Protocol (stdio)
       v
Geepers MCP Plugin (6 MCP Servers)
  |           |           |           |
  v           v           v           v
Unified    Providers    Data       Cache
Orchestr.   Server    Fetching   Manager
  |           |           |           |
  v           v           v           v
Utilities  Web Search  Document   Redis
 Server     Server    Generator   Cache

Beltalowda orchestration flow:

1. Break a research task into 8 specialized angles
2. Run agents in parallel: arXiv, Semantic Scholar, news, Wikipedia, GitHub, YouTube, financial data, Open Library
3. Mid-level synthesis (Drummer) finds patterns, themes, contradictions
4. Executive synthesis (Camina) produces a summary with key insights
5. Generate PDF, DOCX, and Markdown reports with citations
6. Return structured OrchestratorResult with all outputs and metadata

---

Orchestration tools

Start with the Unified Orchestrator Server:

Tool	What it does
orchestrate_research	Beltalowda: 8 agents, Drummer synthesis, Camina summary
orchestrate_search	Swarm: 5+ specialized parallel agents
get_orchestration_status	Check progress of a running workflow
cancel_orchestration	Stop mid-execution
list_orchestrator_patterns	List available patterns
list_registered_tools	Browse all tool modules
execute_registered_tool	Run any tool directly

---

Data sources

32+ tool modules across seven categories:

• Academic: arXiv, Semantic Scholar, PubMed, Wikipedia, Open Library
• News: NewsAPI, RSS feeds, YouTube
• Code: GitHub repos, commits, user profiles
• Finance: stocks, company fundamentals, market news
• Science: NASA (APOD, Mars photos, satellite imagery)
• Weather: current conditions, forecasts, air quality
• Web: Brave Search, SerpAPI, generic web search

---

LLM providers

Unified interface across 9 providers:

Provider	Chat	Vision	Image Gen
Anthropic (Claude)	yes	yes	no
OpenAI (GPT)	yes	yes	yes
xAI (Grok)	yes	yes	yes
Mistral	yes	yes	no
Cohere	yes	no	no
Google (Gemini)	yes	yes	no
Perplexity	yes	yes	no
Groq (Llama)	yes	no	no
HuggingFace	yes	yes	yes

---

Installation

# Everything
pip install geepers-mcp[all]

# Specific providers only
pip install geepers-mcp[anthropic,openai,xai]

# From source
git clone https://github.com/lukeslp/geepers-mcp.git
cd geepers-mcp
pip install -e .[all]

.env reference

# LLM Providers (at least one required)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
XAI_API_KEY=xai-...
MISTRAL_API_KEY=...
COHERE_API_KEY=...
GEMINI_API_KEY=...
PERPLEXITY_API_KEY=...
GROQ_API_KEY=...
HUGGINGFACE_API_KEY=...

# Data APIs (optional)
YOUTUBE_API_KEY=...
GITHUB_TOKEN=ghp_...
NASA_API_KEY=...
NEWS_API_KEY=...
ALPHAVANTAGE_API_KEY=...
OPENWEATHER_API_KEY=...

# Caching (optional)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=...

# Documents (optional)
DEFAULT_DOCUMENT_FORMAT=pdf
CITATION_STYLE=apa

MCP configuration

The plugin auto-configures .mcp.json. To override manually:

{
  "mcpServers": {
    "geepers-unified": {
      "command": "python",
      "args": ["-m", "geepers_mcp.mcp.stdio_servers.unified_stdio"],
      "env": {
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

Verify

python -c "from geepers_mcp.config import ConfigManager; print('OK')"

---

Custom orchestrators

from shared.orchestration import BaseOrchestrator, OrchestratorConfig, SubTask, AgentType

class MyOrchestrator(BaseOrchestrator):
    async def decompose_task(self, task, context=None):
        return [
            SubTask(id="step1", description="First step", agent_type=AgentType.RESEARCHER),
            SubTask(id="step2", description="Second step", agent_type=AgentType.SYNTHESIZER)
        ]

    async def execute_subtask(self, subtask, context=None):
        result = await self.provider.complete(subtask.description)
        return SubTaskResult(subtask_id=subtask.id, output=result)

    async def synthesize_results(self, results, context=None):
        combined = "\n".join([r.output for r in results])
        return SynthesisResult(output=combined)

---

Troubleshooting

"No module named 'shared'"

pip install geepers-kernel

"No module named 'geepers_mcp'"

pip install geepers-mcp

"Provider not available: anthropic"

pip install geepers-mcp[anthropic]
echo $ANTHROPIC_API_KEY  # verify key is set

"Redis connection failed"

redis-server
# or disable caching:
export REDIS_ENABLED=false

Debug mode:

export GEEPERS_DEBUG=true
export LOG_LEVEL=DEBUG

---

Naming hierarchy

Role	Responsibility	Pattern
Conductor	Top-level coordinator	conductor_<slug>
Orchestrator	Mid-tier decomposition	orchestrator_<slug>
Agent	Narrow specialist	agent_<slug>
Utility	Atomic tool	utility_<slug>

---

License

MIT License. See LICENSE.

Luke Steuber

• dr.eamer.dev
• @lukesteuber.com