a2a-bridge-mcp-server

Agent-to-Agent Bridge MCP Server for seamless Claude Code and Gemini CLI integration with automatic installation and configuration.

🚀 Quick Start

One-Command Installation

npx a2a-bridge-mcp-server install

That's it! The installer will:

• ✅ Detect your operating system
• ✅ Check/install Gemini CLI
• ✅ Configure Claude Desktop automatically
• ✅ Test the installation
• ✅ Provide setup guidance

Alternative Installation Methods

# Global installation
npm install -g a2a-bridge-mcp-server
a2a-mcp-install install

# Manual configuration
a2a-bridge-mcp setup
a2a-bridge-mcp test

🌟 Features

• 🌉 Seamless Integration: Bridge Claude Code with Gemini CLI via standardized protocols
• 🔄 Automatic Setup: One-command installation with OS detection and configuration
• 🔐 Flexible Authentication: Support for both API keys and Google OAuth
• 🤖 AI-to-AI Communication: Real-time message routing via A2A protocol
• 📡 Agent Discovery: Automatic agent registration and capability detection
• 💾 Persistent Storage: Agent registry and task history management
• ⚡ Real-time Processing: Instant message routing and response handling
• 🛠️ Complete MCP Tools: Full suite of agent management and communication tools
• 🔧 Smart Configuration: Automatic Claude Desktop configuration across platforms

🛠️ Available MCP Tools

Once installed, these tools will be available in Claude Code:

Core A2A Bridge Tools

| Tool | Description | Parameters | |------|-------------|------------| | register_agent | Register A2A-compatible agents | url, name? | | list_agents | List all registered agents | - | | send_message | Send messages to agents | agent_url, message, session_id? | | get_task_result | Retrieve task results | task_id |

Direct Gemini Integration

| Tool | Description | Parameters | |------|-------------|------------| | gemini_chat | Chat directly with Gemini AI | prompt, model? |

📋 System Requirements

• Node.js: 18.0.0 or higher
• Operating System: macOS, Linux, or Windows (with WSL)
• Claude Desktop: Latest version installed
• Gemini CLI: Will be installed automatically or prompt for installation

🔧 CLI Commands

Installation & Setup

a2a-mcp-install install    # Interactive installation
a2a-mcp-install test       # Test installation
a2a-mcp-install uninstall  # Remove installation

Server Management

a2a-bridge-mcp start       # Start MCP server
a2a-bridge-mcp status      # Check status
a2a-bridge-mcp setup       # Configure manually
a2a-bridge-mcp test        # Run diagnostics

🖥️ Platform Support

macOS

• ✅ Claude Desktop auto-configuration
• ✅ Automatic Gemini CLI installation
• ✅ OAuth and API key authentication
• ✅ Full MCP integration

Linux

• ✅ Claude Desktop auto-configuration
• ✅ Automatic Gemini CLI installation
• ✅ OAuth and API key authentication
• ✅ Full MCP integration

Windows

• ⚠️ Requires WSL (Windows Subsystem for Linux)
• ✅ Claude Desktop configuration (in Windows)
• ✅ Gemini CLI installation (in WSL)
• ✅ Cross-platform bridge functionality

🔐 Authentication Options

Option 1: Google API Key (Recommended for Development)

1. Get your API key: https://aistudio.google.com/app/apikey
2. The installer will prompt for it, or set GOOGLE_API_KEY environment variable

Option 2: OAuth (Recommended for Personal Use)

1. Run: gemini auth
2. Complete Google authentication in browser
3. The installer will detect and verify authentication

📁 Configuration Files

Claude Desktop Config

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

A2A Bridge Data

• Storage: ~/.a2a-bridge/
• Agents: registered_agents.json
• Tasks: task_agent_mapping.json

🎯 Usage Examples

In Claude Code

1. List available agents:

   Show me all registered A2A agents

2. Chat with Gemini:

   Use Gemini to explain the difference between async and await in JavaScript

3. Send message to agent:

   Send a message to the Gemini agent asking about Python best practices

4. Register new agent:

   Register the agent at http://my-ai-service:8080 with name "My Custom AI"

Command Line Testing

# Check everything is working
a2a-bridge-mcp test

# Start in interactive mode for debugging
a2a-bridge-mcp start --interactive

# Check detailed status
a2a-bridge-mcp status

🔍 Troubleshooting

Common Issues

"Gemini CLI not found"

npm install -g @google/gemini-cli
gemini --version

"Authentication failed"

# Option 1: OAuth
gemini auth

# Option 2: API Key
export GOOGLE_API_KEY="your-api-key-here"

"MCP server not loading in Claude"

1. Restart Claude Desktop completely
2. Check configuration: a2a-bridge-mcp status
3. View Claude Desktop Developer tab for errors

"Installation fails"

# Run with debugging
NODE_ENV=development a2a-mcp-install install

# Check permissions
sudo chown -R $USER ~/.a2a-bridge

Debug Mode

Enable detailed logging:

export DEBUG=a2a-bridge:*
export NODE_ENV=development
a2a-bridge-mcp start

Getting Help

a2a-bridge-mcp help
a2a-mcp-install --help

🏗️ Development

Local Development Setup

# Clone the repository
git clone https://github.com/a2a-bridge-project/mcp-server
cd mcp-server/npm-package

# Install dependencies
npm install

# Build the package
npm run build

# Test locally
npm link
a2a-mcp-install install

Testing

npm test                    # Run test suite
npm run test:integration   # Integration tests
npm run test:cli          # CLI tests

Building

npm run build     # Build for distribution
npm run dev       # Development mode
npm run prepare   # Pre-publish build

📦 Publishing

# Build and test
npm run build
npm test

# Publish to npm
npm publish --access public

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes and add tests
4. Run tests: npm test
5. Commit with conventional commits: feat: add new feature
6. Push and create a Pull Request

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• Desktop Extension: One-click installation via DXT format
• Docker Version: Containerized deployment option
• Python Bridge: Original Python implementation
• Claude Code: AI-powered development environment

📚 Documentation

• Installation Guide
• Configuration Reference
• API Documentation
• Troubleshooting Guide
• Development Guide

🌟 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]
• 🌐 Website: https://a2a-bridge-project.com

Made with ❤️ for the AI development community

Enable seamless AI-to-AI collaboration in your development workflow! 🚀