ivangrynenko/gemini_mcp

Gemini MCP Server Architecture Plan

Overview

An MCP server that enables Claude to orchestrate multiple Gemini AI agents dynamically, with each agent maintaining its own conversational context through persistent sessions.

✅ Implementation Status

COMPLETED - The Gemini MCP server is now fully implemented and ready for use!

What's Implemented:

• ✅ Complete MCP server with all 6 tool functions
• ✅ Dynamic agent creation and management
• ✅ Gemini API integration with session management
• ✅ Both in-memory and SQLite storage options
• ✅ Context handoff between agents
• ✅ Automatic session cleanup
• ✅ Comprehensive error handling
• ✅ Background cleanup tasks
• ✅ Full conversation history tracking

Quick Start

1. Installation

# Clone or navigate to the project directory
cd gemini_mcp

# Install dependencies
pip install -r requirements.txt

2. Configuration

Create a .env file with your Gemini API key:

# Copy the example environment file
cp .env.example .env

# Edit .env and add your Gemini API key
GEMINI_API_KEY=your-actual-api-key-here

3. Configure Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "gemini-orchestrator": {
      "command": "python",
      "args": ["-m", "gemini_mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here",
        "STORAGE_TYPE": "memory"
      }
    }
  }
}

4. Run the Server

# Run directly
python -m gemini_mcp

# Or run the main module
python __main__.py

5. Test Basic Functionality

# Run basic tests
python tests/test_basic.py

Usage Examples

Creating and Using Agents

Claude: "I need to set up a development team for a new project."

# Create a business analyst
ai_agents_create(
    role="business_analyst",
    system_prompt="You are an experienced business analyst specialising in requirements gathering and stakeholder management. Focus on understanding business needs and translating them into clear, actionable requirements."
)

# Create a software architect  
ai_agents_create(
    role="architect",
    system_prompt="You are a senior software architect with expertise in scalable system design, microservices, and cloud architecture. Provide technical solutions that are robust, maintainable, and future-proof."
)

# Get requirements from business analyst
ai_agents_send_message(
    role="business_analyst",
    message="What are the key considerations for building a task management system for a remote team of 50 people?"
)

# Hand off context to architect
ai_agents_handoff(
    from_role="business_analyst",
    to_role="architect", 
    context_summary="Requirements gathered for a task management system: 50 remote users, needs real-time collaboration, mobile support, integration with existing tools, and strong security.",
    include_full_history=true
)

# Get architectural recommendations
ai_agents_send_message(
    role="architect",
    message="Based on these requirements, what architecture would you recommend and what are the key technical decisions we need to make?"
)

Managing Agents

# List all active agents
ai_agents_list()

# Get conversation history
ai_agents_get_conversation(
    role="architect",
    last_n_messages=10
)

# Delete an agent when done
ai_agents_delete(role="business_analyst")

Core Architecture

1. Dynamic Agent Management

Key Principle: Agents are created on-demand during conversations, not pre-configured.

Claude → MCP Server → Gemini API
         ↓
    Session Store
    (Memory/SQLite)

2. Storage Options

In-Memory Storage (RAM)

• Pros: Lightning fast, no I/O overhead
• Cons: Data lost on server restart
• Use Case: Development, testing, short-lived sessions

SQLite Storage

• Pros: Persistent, lightweight, no external dependencies
• Cons: Slightly slower than memory
• Implementation: Auto-initialised database file in project directory

# Auto-initialisation example
db_path = Path(__file__).parent / "sessions.db"
if not db_path.exists():
    initialise_database(db_path)

MCP Tool Functions

1. ai_agents_create

{
    "name": "ai_agents_create",
    "description": "Create a new Gemini agent with a specific role",
    "parameters": {
        "role": "string (e.g., 'architect', 'tester')",
        "system_prompt": "string (defines agent behaviour)",
        "session_id": "optional string (auto-generated if not provided)"
    }
}

2. ai_agents_send_message

{
    "name": "ai_agents_send_message",
    "description": "Send a message to a specific agent",
    "parameters": {
        "role": "string (agent role)",
        "message": "string (prompt to send)",
        "include_context": "boolean (whether to include previous context)"
    }
}

3. ai_agents_list

{
    "name": "ai_agents_list",
    "description": "List all active agents and their sessions",
    "returns": [
        {
            "role": "string",
            "session_id": "string",
            "created_at": "timestamp",
            "last_interaction": "timestamp",
            "message_count": "integer"
        }
    ]
}

4. ai_agents_get_conversation

{
    "name": "ai_agents_get_conversation",
    "description": "Retrieve conversation history for an agent",
    "parameters": {
        "role": "string",
        "last_n_messages": "integer (optional, default all)"
    }
}

5. ai_agents_handoff

{
    "name": "ai_agents_handoff",
    "description": "Pass context from one agent to another",
    "parameters": {
        "from_role": "string",
        "to_role": "string",
        "context_summary": "string (what to pass along)",
        "include_full_history": "boolean"
    }
}

6. ai_agents_delete

{
    "name": "ai_agents_delete",
    "description": "Remove an agent and its session",
    "parameters": {
        "role": "string"
    }
}

Session Schema

Memory Storage Structure

sessions = {
    "architect_1234": {
        "role": "architect",
        "session_id": "1234",
        "gemini_session": "gemini_session_abc123",
        "system_prompt": "You are a software architect...",
        "created_at": "2024-01-01T10:00:00Z",
        "last_interaction": "2024-01-01T11:30:00Z",
        "messages": [
            {"role": "user", "content": "...", "timestamp": "..."},
            {"role": "assistant", "content": "...", "timestamp": "..."}
        ]
    }
}

SQLite Schema

CREATE TABLE IF NOT EXISTS agents (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    role TEXT UNIQUE NOT NULL,
    session_id TEXT UNIQUE NOT NULL,
    gemini_session TEXT,
    system_prompt TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_interaction TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    agent_id INTEGER,
    role TEXT NOT NULL,
    content TEXT NOT NULL,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (agent_id) REFERENCES agents(id)
);

CREATE TABLE IF NOT EXISTS handoffs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    from_agent_id INTEGER,
    to_agent_id INTEGER,
    context_summary TEXT,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (from_agent_id) REFERENCES agents(id),
    FOREIGN KEY (to_agent_id) REFERENCES agents(id)
);

Configuration

Environment Variables

{
    "mcpServers": {
        "gemini-orchestrator": {
            "command": "python",
            "args": ["-m", "gemini_mcp"],
            "env": {
                "GEMINI_API_KEY": "your-api-key-here",
                "GEMINI_MODEL": "gemini-1.5-pro",
                "STORAGE_TYPE": "memory|sqlite",
                "SQLITE_PATH": "./sessions.db",
                "SESSION_TIMEOUT_HOURS": "24",
                "MAX_AGENTS": "10"
            }
        }
    }
}

Usage Example

Claude's Workflow

1. Initialise Project Team

Claude: "I'll set up a development team for your project."

ai_agents_create(
    role="business_analyst",
    system_prompt="You are a business analyst focusing on requirements gathering..."
)

ai_agents_create(
    role="architect",
    system_prompt="You are a software architect designing scalable systems..."
)

2. Gather Requirements

Claude: "Let me ask our business analyst about the requirements."

ai_agents_send_message(
    role="business_analyst",
    message="What are the key functional requirements for a task management system?"
)

3. Design Architecture

Claude: "Now I'll have our architect design the system based on these requirements."

ai_agents_handoff(
    from_role="business_analyst",
    to_role="architect",
    context_summary="Key requirements: multi-user support, real-time updates, mobile-first..."
)

ai_agents_send_message(
    role="architect",
    message="Based on these requirements, what architecture would you recommend?"
)

Development Roadmap

For detailed development plans, security considerations, and future enhancements, see .

Current Status: Version 1.0 is complete and production-ready ✅

Next Steps: Version 1.1 focuses on security, reliability, and observability improvements. All roadmap items are tracked as GitHub Issues.

Package Structure

gemini_mcp/
├── README.md
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
├── __init__.py
├── __main__.py
├── server.py
├── storage/
│   ├── __init__.py
│   ├── memory.py
│   └── sqlite.py
├── agents/
│   ├── __init__.py
│   └── manager.py
├── gemini/
│   ├── __init__.py
│   └── client.py
├── tests/
│   ├── __init__.py
│   └── test_basic.py
└── sessions.db (auto-created)

Troubleshooting

Common Issues

1. "GEMINI_API_KEY not found"

   • Ensure you've set the environment variable
   • Check your .env file exists and has the correct key

2. "Rate limit reached"

   • Gemini API has rate limits
   • Wait 60 seconds and retry
   • Consider upgrading your API quota

3. "Agent not found"

   • Verify the agent role exists with list_agents()
   • Check for typos in the role name

4. SQLite permission errors

   • Ensure the directory is writable
   • Check file permissions on the database

Getting Help

• Check the logs for detailed error messages
• Run the basic tests to verify functionality
• Review the configuration settings
• Ensure all dependencies are installed

Contributing

Contributions are welcome! See for development priorities and GitHub Issues for specific tasks.

Development Guidelines

• Follow PEP 8 style guide
• Add tests for new features
• Update documentation
• Use type hints
• Profile before optimising

Ready to use! The Gemini MCP server is fully implemented and ready for production use with Claude Desktop.