trackmcp
Back to directory
gongrzhe

ACP-MCP-Server

View on GitHub

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.

10 stars PythonAI & Machine Learning Updated Oct 3, 2025

Documentation

ACP-MCP-Server

PyPI version
Python 3.11+
License: 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

code
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

code
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   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 file for details.

🔗 Related Projects

📞 Support

Frequently asked questions

What is ACP-MCP-Server?

ACP-MCP-Server is 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.

How do I install ACP-MCP-Server?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is ACP-MCP-Server open source?

Yes — it is hosted on GitHub at https://github.com/gongrzhe/acp-mcp-server and has 10 stars.

Related MCP tools

All-Hands-AIopenhands

🙌 OpenHands: Code Less, Make More for the Model Context Protocol. Enhance AI assistants with powerful integrations. Python-based implementation.

64,677 Python
agentartificial-intelligencechatgpt+6
mem0aimem0

Universal memory layer for AI Agents; Announcing OpenMemory MCP - local and secure memory management. Python-based implementation.

42,646 Python
agentsaiai-agents+12
zhayujiechatgpt-on-wechat

基于大模型搭建的聊天机器人，同时支持 微信公众号、企业微信应用、飞书、钉钉 等接入，可选择ChatGPT/Claude/DeepSeek/文心一言/讯飞星火/通义千问/ Gemini/GLM-4/Kimi/LinkAI，能处理文本、语音和图片，访问操作系统和互联网，支持基于自有知识库进行定制企业智能客服。

39,573 Python
aiai-agentchatgpt+17
assafelovicgpt-researcher

An LLM agent that conducts deep research (local and web) on any given topic and generates a long report with citations. Built for the Model Context Protocol to

24,026 Python
agentaiautomation+8
jlowinfastmcp

🚀 The fast, Pythonic way to build MCP servers and clients Trusted by 19900+ developers. Trusted by 19900+ developers. Trusted by 19900+ developers.

19,927 Python
agentsfastmcpllms+6
1Panel-devmaxkb

🔥 MaxKB is an open-source platform for building enterprise-grade agents. MaxKB 是强大易用的开源企业级智能体平台。 for the Model Context Protocol. Enhance AI assistants with po

19,062 Python
agentagentic-aichatbot+11

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP