https://github.com/GongRzhe/ACP-MCP-Server
A bridge server that connects Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients, enabling seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop.
https://github.com/GongRzhe/ACP-MCP-Server
Last synced: about 2 months ago
JSON representation
A bridge server that connects Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients, enabling seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop.
- Host: GitHub
- URL: https://github.com/GongRzhe/ACP-MCP-Server
- Owner: GongRzhe
- License: mit
- Created: 2025-06-04T07:53:55.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-06-18T08:48:15.000Z (5 months ago)
- Last Synced: 2025-06-29T11:06:45.123Z (4 months ago)
- Language: Python
- Homepage:
- Size: 56.6 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **ACP-MCP-Server** - A bridge server that connects Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients, enabling seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop. `python` `mcp` `server` `ai` `ml` `pip install git+https://github.com/GongRzhe/ACP-MCP-Server` (AI/ML)
- awesome-mcp-servers - **ACP-MCP-Server** - A bridge server that connects Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients, enabling seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop. `python` `mcp` `server` `ai` `ml` `pip install git+https://github.com/GongRzhe/ACP-MCP-Server` (🤖 AI/ML)
README
# ACP-MCP-Server
[](https://badge.fury.io/py/acp-mcp-server)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A bridge server that connects **Agent Communication Protocol (ACP)** agents with **Model Context Protocol (MCP)** clients, enabling seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop.
## ✨ Features
- 🔄 **Protocol Bridge**: Seamlessly connects ACP agents with MCP clients
- 🚀 **Multiple Transports**: Supports STDIO, SSE, and Streamable HTTP
- 🤖 **Agent Discovery**: Automatic discovery and registration of ACP agents
- 🧠 **Smart Routing**: Intelligent routing of requests to appropriate agents
- 🔄 **Async Support**: Full support for synchronous and asynchronous operations
- 💬 **Interactive Sessions**: Support for multi-turn agent interactions
- 🌐 **Multi-Modal**: Handle text, images, and other content types
## 🚀 Quick Start
### Installation
```bash
# Install from PyPI
pip install acp-mcp-server
# Or use uvx for isolated execution
uvx acp-mcp-server
```
### Basic Usage
```bash
# Run with STDIO (default, for Claude Desktop)
acp-mcp-server
# Run with SSE transport
acp-mcp-server --transport sse --port 8000
# Run with HTTP transport
acp-mcp-server --transport streamable-http --host 0.0.0.0 --port 9000
# Connect to different ACP server
acp-mcp-server --acp-url http://localhost:8001
```
### Using with Claude Desktop
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"acp-bridge": {
"command": "uvx",
"args": ["acp-mcp-server"]
}
}
}
```
## 📋 Requirements
- Python 3.11+
- Running ACP server with agents
- FastMCP for protocol implementation
## 🔧 Configuration
### Environment Variables
- `ACP_BASE_URL`: ACP server URL (default: `http://localhost:8000`)
### Command Line Options
```
usage: acp-mcp-server [-h] [--transport {stdio,sse,streamable-http}] [--host HOST] [--port PORT] [--path PATH] [--acp-url ACP_URL] [--version]
options:
-h, --help show this help message and exit
--transport {stdio,sse,streamable-http}
Transport protocol (default: stdio)
--host HOST Host address for HTTP transports (default: 127.0.0.1)
--port PORT Port number for HTTP transports (default: 8000)
--path PATH URL path for HTTP transports (default: /mcp)
--acp-url ACP_URL ACP server URL (default: http://localhost:8000)
--version show program's version number and exit
```
## 🛠️ Available Tools
The bridge server provides several MCP tools:
### Agent Management
- `discover_acp_agents`: Discover available ACP agents
- `get_agent_info`: Get detailed information about specific agents
### Agent Execution
- `run_acp_agent`: Execute agents in sync/async modes
- `get_async_run_result`: Retrieve results from async executions
- `list_active_runs`: List all active agent runs
### Smart Routing
- `smart_route_request`: Intelligently route requests to best agents
- `test_routing`: Test routing logic without execution
- `add_routing_rule`: Add custom routing rules
- `list_routing_strategies`: View all routing strategies
### Interactive Sessions
- `start_interactive_agent`: Start interactive agent sessions
- `provide_user_input`: Provide input to waiting agents
- `list_pending_interactions`: View pending interactions
### Message Processing
- `convert_acp_message`: Convert between ACP and MCP formats
- `analyze_message_content`: Analyze message structure and content
## 🏗️ Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP Client │ │ ACP-MCP Bridge │ │ ACP Agents │
│ (Claude Desktop)│◄──►│ Server │◄──►│ (echo, chat, │
│ │ │ │ │ translate...) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
MCP Protocol Protocol Bridge ACP Protocol
(STDIO/SSE/HTTP) (FastMCP + aiohttp) (HTTP/WebSocket)
```
## 🔌 Transport Modes
### STDIO (Default)
Perfect for Claude Desktop integration:
```bash
acp-mcp-server
```
### SSE (Server-Sent Events)
For web applications and streaming:
```bash
acp-mcp-server --transport sse --port 8000
```
### Streamable HTTP
For REST API integration:
```bash
acp-mcp-server --transport streamable-http --port 9000
```
## 🐳 Docker
### Quick Start with Docker
```bash
# Build the image
docker build -t acp-mcp-server .
# Run with Streamable HTTP transport
docker run -p 9000:9000 acp-mcp-server
# Run with SSE transport
docker run -p 8000:8000 acp-mcp-server \
--transport sse --host 0.0.0.0 --port 8000
# Connect to custom ACP server
docker run -p 9000:9000 -e ACP_BASE_URL=http://my-acp-server:8001 acp-mcp-server
```
### Using Docker Compose
```bash
# Run HTTP transport service
docker-compose up acp-mcp-http
# Run SSE transport service
docker-compose up acp-mcp-sse
# Run both services
docker-compose up
# Run development mode with live code reload
docker-compose --profile dev up acp-mcp-dev
```
### Production Docker Image
For production deployments, use the multi-stage Dockerfile:
```bash
# Build production image
docker build -f Dockerfile.prod -t acp-mcp-server:prod .
# Run production container
docker run -d \
--name acp-mcp-server \
--restart unless-stopped \
-p 9000:9000 \
-e ACP_BASE_URL=http://your-acp-server:8000 \
acp-mcp-server:prod
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Related Projects
- [FastMCP](https://github.com/jlowin/fastmcp) - Fast, Pythonic MCP server framework
- [ACP SDK](https://github.com/i-am-bee/acp) - Agent Communication Protocol SDK
- [Claude Desktop](https://claude.ai/desktop) - AI assistant with MCP support
## 📞 Support
- 🐛 [Report Issues](https://github.com/GongRzhe/ACP-MCP-Server/issues)
- 💬 [Discussions](https://github.com/GongRzhe/ACP-MCP-Server/discussions)
- 📖 [Documentation](https://github.com/GongRzhe/ACP-MCP-Server#readme)