Google ADK MCP Server

A standalone MCP (Model Context Protocol) server that exposes Google Agent Development Kit (ADK) functionality to MCP clients.

Important Links: ADK Docs, ADK Repository, MCP Specification & MCP Documentation.

This standalone MCP server allows any MCP-compatible client (such as Claude Desktop, Cursor IDE, or custom applications) to leverage Google's powerful Agent Development Kit for building, running, and managing AI agents.

---

✨ Key Features

• Complete ADK Integration: Create, configure, and run Google ADK agents through MCP
• Multi-Agent Systems: Build sophisticated multi-agent architectures with coordinators and sub-agents
• Rich Tool Ecosystem: Access ADK's built-in tools (Google Search, web scraping, etc.) and integrate external MCP tools
• Agent Evaluation: Test and evaluate agent performance with structured test cases
• Session Management: Maintain conversation history and state across interactions
• Real-time Execution: Run agents and get responses through the MCP protocol
• IDE Integration: Works with Claude Desktop, Cursor IDE, and other MCP clients

🛠 Available MCP Tools

The server exposes 12 tools to MCP clients:

Agent Management

• create_adk_agent - Create new ADK agents with custom configurations
• list_adk_agents - List all created agents
• get_adk_agent_info - Get detailed information about specific agents
• run_adk_agent - Execute agents with user messages and get responses

Multi-Agent Systems

• create_multi_agent_system - Create coordinator agents with sub-agents
• add_mcp_tools_to_agent - Integrate external MCP servers into ADK agents

Evaluation & Testing

• evaluate_adk_agent - Run test cases against agents and get performance metrics
• list_available_tools - Discover available ADK tools

Utility Tools

• search_web - Perform Google searches
• load_webpage_content - Extract content from web pages
• get_adk_documentation - Access ADK documentation and help
• get_server_version - Get server version and capability information

🚀 Installation

Prerequisites

• Python 3.10 or higher (required for MCP support)
• Google Cloud credentials (required for agent execution and web search functionality)
• Git (for cloning the repository)

Python Version Requirements

MCP requires Python 3.10+. If you have an older version:

• macOS with Homebrew: brew install python@3.11
• Ubuntu/Debian: sudo apt-get install python3.11
• Windows: Download from python.org

Google Cloud Setup (Required)

For full functionality, you need Google Cloud credentials:

1. Google AI API Key (simpler setup) - Get from Google AI Studio
2. Google Cloud Project (full features) - Set up at Google Cloud Console

Install Dependencies

Quick Setup (Recommended)

# Clone the repository
git clone https://github.com/your-username/google-adk-mcp-server.git
cd google-adk-mcp-server

# Run the automated setup script
chmod +x setup.sh
./setup.sh

Manual Setup

# Create a virtual environment (Python 3.10+ required)
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install all dependencies
pip install -r requirements.txt

# Verify installation
python simple_test.py

Environment Setup

⚠️ Required: Set up Google Cloud credentials for agent execution and web search:

Option 1: Google AI API Key (Recommended for getting started)

# Set your Google AI API key
export GOOGLE_AI_API_KEY="your-api-key-here"

Option 2: Google Cloud Project (Full features)

# Set up Google Cloud credentials using service account
export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/service-account-key.json"

# Or authenticate using gcloud CLI
gcloud auth application-default login

# Set your Google Cloud project
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"  # or your preferred region

📖 Usage

Running the MCP Server

As a Standalone Server

# Run the MCP server directly
python mcp_server.py

With MCP Clients

Claude Desktop Configuration

Add to your Claude Desktop MCP configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "google-adk": {
      "command": "python",
      "args": ["/path/to/google-adk-mcp-server/mcp_server.py"]
    }
  }
}

Cursor IDE Configuration

See examples/CURSOR_SETUP.md for detailed Cursor integration instructions.

🎯 Example Workflows

1. Creating a Research Assistant

{
  "tool": "create_adk_agent",
  "arguments": {
    "name": "research_assistant",
    "instruction": "You are a research assistant that helps users find and analyze information from the web. Always provide sources and summarize key findings.",
    "description": "AI assistant specialized in web research and analysis",
    "model": "gemini-2.0-flash",
    "tools": ["google_search", "load_web_page"]
  }
}

2. Building a Multi-Agent System

{
  "tool": "create_multi_agent_system",
  "arguments": {
    "coordinator_name": "customer_service_coordinator",
    "coordinator_instruction": "You coordinate customer service requests by routing them to the appropriate specialist agent.",
    "sub_agents": ["faq_agent", "technical_support", "sales_info"],
    "model": "gemini-2.0-flash"
  }
}

3. Agent Evaluation

{
  "tool": "evaluate_adk_agent",
  "arguments": {
    "agent_name": "research_assistant",
    "test_cases": [
      {
        "input": "Find information about climate change effects",
        "expected_output": "climate change"
      }
    ]
  }
}

🔧 Configuration

Agent Models

Supported models include:

• gemini-2.0-flash (default)
• gemini-1.5-pro
• gemini-1.5-flash

Available Tools

Built-in ADK tools that can be added to agents:

• google_search - Web search functionality
• load_web_page - Web page content extraction

External MCP Integration

You can integrate external MCP servers into your ADK agents:

{
  "tool": "add_mcp_tools_to_agent",
  "arguments": {
    "agent_name": "my_agent",
    "mcp_server_command": "npx",
    "mcp_server_args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
    "tool_filter": ["read_file", "list_directory"]
  }
}

🧪 Development

Project Structure

google-adk-mcp-server/
├── mcp_server.py              # Main MCP server implementation
├── version.py                 # Version management
├── requirements.txt           # Dependencies (uses google-adk as dependency)
├── pyproject.toml            # Project configuration
├── README.md                 # This file
├── CHANGELOG.md              # Version history
├── VERSIONING.md             # Versioning system documentation
├── setup.sh                  # Automated setup script
├── simple_test.py            # Basic functionality tests
├── examples/                 # Configuration examples and tests
│   ├── claude_desktop_config.json
│   ├── cursor_mcp_config.json
│   ├── CURSOR_SETUP.md
│   └── test_mcp_client.py
├── scripts/                  # Release automation
│   └── release.sh
└── .github/workflows/        # CI/CD pipelines
    ├── ci.yml
    └── release.yml

Running Tests

# Run basic functionality test
python simple_test.py

# Run comprehensive test suite
python examples/test_mcp_client.py

# Install development dependencies
pip install -e ".[dev]"

Versioning

This project uses semantic versioning. See VERSIONING.md for details.

# Create a new release
./scripts/release.sh patch   # 1.0.0 → 1.0.1
./scripts/release.sh minor   # 1.0.0 → 1.1.0  
./scripts/release.sh major   # 1.0.0 → 2.0.0

📚 Documentation

Project Documentation

• USAGE.md - Detailed usage guide with examples
• VERSIONING.md - Versioning system and release process
• CHANGELOG.md - Version history and changes
• examples/CURSOR_SETUP.md - Cursor IDE integration

ADK Documentation

• ADK Docs - Complete ADK documentation
• ADK Repository - Google ADK source code
• ADK API Reference - API reference

MCP Documentation

• MCP Specification - Official MCP protocol specification
• MCP Documentation - MCP guides and tutorials

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Fork and clone the repository
2. Install development dependencies: pip install -e ".[dev]"
3. Run tests to ensure everything works
4. Make your changes and add tests
5. Submit a pull request

🐛 Troubleshooting

Common Issues

1. MCP Connection Fails

   • Ensure Python 3.10+ is being used
   • Check that mcp package is installed
   • Verify the server path in client configuration

2. ADK Agent Creation Fails

   • Check Google Cloud credentials are configured
   • Verify model names are correct
   • Ensure google-adk dependency is installed

3. Tool Execution Errors

   • Check tool names are spelled correctly
   • Verify required parameters are provided
   • Look at server logs for detailed error messages

For detailed troubleshooting, see USAGE.md.

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

📝 Changelog

See CHANGELOG.md for a detailed history of changes and version information.

🔗 Related Projects

• Google ADK Python - The core ADK library this server depends on
• Model Context Protocol - The MCP specification and ecosystem

---

A standalone MCP server that brings Google's powerful Agent Development Kit to the Model Context Protocol ecosystem!