Arena
mcp_arena is a production-ready Python library for building MCP (Model Context Protocol) servers with intelligent agent orchestration and domain-specific presets.
Installation
npx mcp-arenaAsk AI about Arena
Powered by Claude Β· Grounded in docs
I know everything about Arena. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
mcp_arena
mcp_arena is a production-ready Python library for building MCP (Model Context Protocol) servers with intelligent agent orchestration and domain-specific presets.
β¨ Features
- π Ready-to-use MCP servers for popular platforms (GitHub, Slack, Notion, AWS, etc.)
- π€ Intelligent agents with reflection, planning, and routing capabilities
- π§ Zero-configuration setup for common use cases
- ποΈ Extensible architecture built on SOLID principles
- π¦ Modular design - use only what you need
π Quick Start
Installation
# Core library
pip install mcp-arena
# With specific presets
pip install mcp-arena[github,slack,notion]
# All presets
pip install mcp-arena[all]
Basic Usage
from mcp_arena.presents.github import GithubMCPServer
# Zero-config GitHub MCP server
mcp_server = GithubMCPServer(token="your_github_token")
mcp_server.run()
Using Tools Directly
from mcp_arena.tools.github import GithubTools
from mcp_arena.presents.github import GithubMCPServer
# Create GitHub MCP server first
mcp_server = GithubMCPServer(token="your_token")
# Create tools wrapper
tool = GithubTools(server=mcp_server)
tools = tool.get_list_of_tools()
@mcp_server.tool()
def add(a: int, b: int) -> int:
"""Add two numbers"""
return a + b
# Add a dynamic greeting resource
@mcp_servevr.resource("greeting://{name}")
def get_greeting(name: str) -> str:
"""Get a personalized greeting"""
return f"Hello, {name}!"
@mcp_server.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
"""Generate a greeting prompt"""
styles = {
"friendly": "Please write a warm, friendly greeting",
"formal": "Please write a formal, professional greeting",
"casual": "Please write a casual, relaxed greeting",
}
return f"{styles.get(style, styles['friendly'])} for someone named {name}."
Advance Documentation
from mcp.server.fastmcp import Icon
from mcp_arena.presents.github import GithubMCPServer
# Create an icon from a file path or URL
icon = Icon(
src="icon.png",
mimeType="image/png",
sizes="64x64"
)
# Add icons to server
mcp = GithubMCPServer(
"My Server",
website_url="https://example.com",
token="*******",
icons=[icon]
)
# Add icons to tools, resources, and prompts
@mcp.tool(icons=[icon])
def my_tool():
"""Tool with an icon."""
return "result"
@mcp.resource("demo://resource", icons=[icon])
def my_resource():
"""Resource with an icon."""
return "content"
With Agent Orchestration
from mcp_arena.presents.github import GithubMCPServer
from mcp_arena.agent.react_agent import ReactAgent
# Create MCP server
mcp_server = GithubMCPServer(token="your_token")
# Create agent separately
agent = ReactAgent(llm=None, memory_type="conversation")
# Run the server
mcp_server.run()
LangChain Integration
Using MCP Arena Wrapper
from mcp_arena.wrapper.langchain_wrapper import MCPLangChainWrapper
from mcp_arena.presents.github import GithubMCPServer
# Create MCP server
github_server = GithubMCPServer(token="your_token")
# Wrap with LangChain
wrapper = MCPLangChainWrapper(
servers={"github": github_server},
auto_start=True
)
# Connect and create agent
await wrapper.connect()
agent = wrapper.create_agent(
llm="gpt-4-turbo",
system_prompt="You are a GitHub assistant"
)
Direct langchain_mcp_adapters Usage
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent
from mcp_arena.presents.github import GithubMCPServer
# Start GitHub MCP server in background
github_server = GithubMCPServer(token="your_token", transport="stdio")
github_server.run()
# Create client with multiple servers
client = MultiServerMCPClient(
{
"github": {
"transport": "stdio",
"command": "python",
"args": ["/path/to/github_server_script.py"],
},
"math": {
"transport": "http",
"url": "http://localhost:8001/mcp",
}
}
)
tools = await client.get_tools()
agent = create_agent(
"claude-sonnet-4-5-20250929",
tools
)
# Use the agent
github_response = await agent.ainvoke(
{"messages": [{"role": "user", "content": "List my GitHub repositories"}]}
)
math_response = await agent.ainvoke(
{"messages": [{"role": "user", "content": "what's (3 + 5) x 12?"}]}
)
π Available Presets
Browser & Automation
- Browser - Browser automation with Playwright (navigate, screenshot, forms, extract data)
- Screen Capture - Take screenshots and screen recordings with PyAutoGUI
Video & Media
- Video - Video editing (trim, merge, effects, format conversion) with FFmpeg
- PDF - PDF processing (extract text/images, merge, split, watermark, encrypt)
- QR Code - Generate and decode QR codes
Data & Files
- Spreadsheet - Excel/CSV read/write with pandas and openpyxl
- Web Scraping - Extract data from websites with requests and BeautifulSoup
Communication
- Slack - Channels, messages, workflows
- WhatsApp - Messaging via Twilio API
- Gmail - Email management and sending
- Outlook - Microsoft 365 email and calendar
- Discord - Servers and channels
- Teams - Microsoft Teams integration
- Notification - Multi-platform notifications (Email, Slack, webhooks)
Development Platforms
- GitHub - Repositories, issues, PRs, workflows
- GitLab - Projects, CI/CD, issues
- Bitbucket - Repositories and pipelines
Productivity
- Notion - Databases, pages, blocks
- Confluence - Spaces and pages
- Jira - Projects, issues, workflows
Cloud Services
- AWS S3 - Storage operations
- Azure Blob - Azure storage
- Google Cloud Storage - GCP storage
System Operations
- Local Operations - File system and system ops
- Docker - Container management
- Kubernetes - Cluster operations
π€ Agent Types
Reflection Agent
Self-improving agent that refines responses through iterative refinement.
from mcp_arena.agent.reflection_agent import ReflectionAgent
agent = ReflectionAgent(
llm=None,
memory_type="conversation"
)
ReAct Agent
Systematic reasoning and acting cycle for complex problem-solving.
from mcp_arena.agent.react_agent import ReactAgent
agent = ReactAgent(
llm=None,
memory_type="conversation"
)
Planning Agent
Goal decomposition and step-by-step execution for complex tasks.
from mcp_arena.agent.planning_agent import PlanningAgent
agent = PlanningAgent(
llm=None,
memory_type="conversation"
)
Router Agent
Dynamic agent selection based on task requirements.
from mcp_arena.agent.router import AgentRouter
router = AgentRouter()
# Add routing rules
router.add_route(
condition=lambda input_text: "github" in input_text.lower(),
agent_type="react",
config={"llm": your_llm}
)
router.add_route(
condition=lambda input_text: "reflect" in input_text.lower(),
agent_type="reflection",
config={"llm": your_llm}
)
π§ Custom Tools
Extend any preset with custom tools:
from mcp_arena.presents.github import GithubMCPServer
from mcp_arena.tools.base import tool
@tool(description="Custom repository analyzer")
def analyze_repo(repo: str) -> str:
return f"Analysis for {repo}"
server = GithubMCPServer(
token="your_token",
extra_tools=[analyze_repo]
)
π€ LangChain Integration
Integrate mcp_arena MCP servers with LangChain agents for powerful multi-service automation:
from langchain_openai import ChatOpenAI
from mcp_arena.wrapper.langchain_wrapper import MCPLangChainWrapper
from mcp_arena.presents.browser import BrowserMCPServer
# Initialize LLM
llm = ChatOpenAI(model="gpt-4-turbo")
# Create wrapper with browser server
wrapper = MCPLangChainWrapper(
servers={"browser": BrowserMCPServer(headless=True)},
auto_start=True
)
# Connect and create agent
await wrapper.connect()
agent = wrapper.create_agent(
llm=llm,
system_prompt="You are a helpful browser automation assistant"
)
# Use the agent
response = await wrapper.invoke_agent(
agent,
"Go to example.com and tell me the page title"
)
Multi-Server Agent Example
from langchain_openai import ChatOpenAI
from mcp_arena.wrapper.langchain_wrapper import MCPLangChainWrapper
from mcp_arena.presents.browser import BrowserMCPServer
from mcp_arena.presents.pdf import PDFMCPServer
from mcp_arena.presents.web_scraping import WebScrapingMCPServer
# Initialize LLM
llm = ChatOpenAI(model="gpt-4-turbo")
# Create wrapper with multiple servers
wrapper = MCPLangChainWrapper(
servers={
"browser": BrowserMCPServer(headless=True),
"pdf": PDFMCPServer(),
"web": WebScrapingMCPServer()
},
auto_start=True
)
# Connect and create agent with all tools
await wrapper.connect()
agent = wrapper.create_agent(
llm=llm,
system_prompt="""You are a powerful research assistant with access to:
- Browser automation (navigate websites, take screenshots)
- PDF processing (extract text, merge, split)
- Web scraping (extract data from websites)
"""
)
# Use the agent
response = await wrapper.invoke_agent(
agent,
"Research climate change: find a Wikipedia article, take a screenshot, and extract key facts to a PDF"
)
Installation:
pip install langchain-openai langchain-mcp-adapters
pip install "mcp-arena[browser,video,pdf,webscraping]"
π Full Documentation π Agent Examples
ποΈ Custom MCP Server
Build from scratch for full control:
from mcp_arena.mcp.server import BaseMCPServer
from mcp_arena.tools.base import tool
@tool(description="Search internal docs")
def search_docs(query: str) -> str:
return f"Results for {query}"
class CustomMCPServer(BaseMCPServer):
def _register_tools(self):
self.add_tool(search_docs)
server = CustomMCPServer(
name="custom-server",
description="Custom MCP server"
)
server.run()
π Documentation
- Installation Guide - Detailed installation instructions for all presets and communication services
- MCP Servers Guide - Comprehensive guide to all 17 available MCP servers
- Agent Guide - Using and configuring intelligent agents
- Tools Guide - Tool development and integration
- LangChain Integration - Integrate MCP servers with LangChain agents
- Quick Start - Get started in minutes
- Tutorial - Step-by-step tutorial
Architecture
MCP Client
β
βΌ
βββββββββββββββββββ
β MCP Server β β Core Layer
β - Protocol β
β - Auth β
β - Tool Registry β
βββββββββββββββββββ
β
βΌ
βββββββββββββββββββ
β Agent System β β Intelligence Layer
β - Reflection β
β - ReAct β
β - Planning β
β - Router β
βββββββββββββββββββ
β
βΌ
βββββββββββββββββββ
β Tool Ecosystem β β Execution Layer
β - Presets β
β - Custom Tools β
β - Orchestration β
βββββββββββββββββββ
Installation Options
# Core only
pip install mcp-arena[core]
# Browser automation
pip install mcp-arena[browser]
# Video editing
pip install mcp-arena[video]
# PDF processing
pip install mcp-arena[pdf]
# QR code generation
pip install mcp-arena[qrcode]
# Spreadsheet operations
pip install mcp-arena[spreadsheet]
# Web scraping
pip install mcp-arena[webscraping]
# Screen capture
pip install mcp-arena[screencapture]
# Cloud storage (AWS S3, GCS, Azure)
pip install mcp-arena[cloudstorage]
# Notifications (Email, Slack, webhooks)
pip install mcp-arena[notification]
# Development platforms
pip install mcp-arena[github,gitlab,bitbucket]
# Data & storage
pip install mcp-arena[postgres,mongodb,redis,vectordb]
# Communication
pip install mcp-arena[slack,whatsapp,gmail,outlook]
# All communication services
pip install mcp-arena[communication]
# Productivity
pip install mcp-arena[notion,confluence,jira]
# Cloud services
pip install mcp-arena[aws,docker,kubernetes]
# System operations
pip install mcp-arena[local_operation]
# Agent framework
pip install mcp-arena[agents]
# All presets
pip install mcp-arena[all]
# Complete with dev tools
pip install mcp-arena[complete]
π€ Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
# Clone the repository
git clone https://github.com/SatyamSingh8306/mcp_arena.git
cd mcp_arena
# Install in development mode
pip install -e .[dev]
# Run tests
pytest
# Run linting
black .
isort .
mypy .
Priority Areas
- New preset implementations
- Agent pattern improvements
- Documentation and examples
- Bug fixes and performance
π Requirements
- Python 3.12+
- MCP client compatible with Model Context Protocol v1.0+
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π Links
- Documentation - Complete documentation library
- Installation Guide - Installation instructions
- MCP Servers Guide - Server documentation
- LangChain Integration - LangChain integration guide
- Repository
- Issues
- PyPI
π§ Status
Version: 0.2.1 (Production-ready)
β Stable Features:
- MCP server base classes
- 17 production-ready presets
- 4 agent types
- Tool registration system
- SOLID architecture
- Communication services (Gmail, Outlook, Slack, WhatsApp)
π Evolving APIs:
- Agent interfaces may enhance based on feedback
- New preset additions
- Performance optimizations
π Production Ready:
- Comprehensive documentation
- Active development
- Community support
