Claude Swarm MCP Server

A Model Context Protocol (MCP) server that enables multi-agent orchestration using Claude AI through Claude Desktop. Create, manage, and coordinate specialized AI agents for complex workflows like financial analysis, customer service, and research.

🚀 Features

• 🤖 Persistent Agents: Create specialized Claude agents that survive restarts
• 🔄 Agent Coordination: Intelligent handoffs between agents based on expertise
• 💾 Local Storage: All agents and conversations saved locally
• 📊 Pre-built Templates: Ready-to-use financial analysis and customer service teams
• 🎯 Specialized Functions: Custom tools and capabilities per agent
• 🔧 Easy Integration: Works seamlessly with Claude Desktop

📋 Quick Start

Prerequisites

• Python 3.10+
• Claude Desktop installed
• Anthropic API key with billing enabled

Installation

1. Clone the repository

git clone https://github.com/yourusername/claude-swarm-mcp.git
cd claude-swarm-mcp

2. Install dependencies

pip install -r requirements.txt

3. Configure Claude Desktop

   Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "claude-swarm": {
      "command": "python3",
      "args": ["/path/to/claude-swarm-mcp/claude_swarm_mcp_server.py"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Start the server

python3 claude_swarm_mcp_server.py

5. Restart Claude Desktop and test with:

Create finance team with company name "Your Company"

🎯 Usage Examples

Create a Financial Analysis Team

Create finance team with company name "TechVest Capital"

This creates 4 specialized agents:

• Risk Analyst - VaR calculations, stress testing
• Portfolio Manager - Asset allocation, optimization
• Data Analyst - Market data, performance metrics
• Research Analyst - Investment research, market analysis

Chat with Specialists

Chat with agent: "Calculate the VaR for a portfolio with AAPL 30%, GOOGL 25%, MSFT 20%, AMZN 15%, TSLA 10%" using agent "Risk Analyst"

Create Custom Agents

Create agent with name "Options Specialist" and instructions "You are an expert in options trading. Calculate Greeks, analyze volatility, and recommend hedging strategies."

List All Agents

List agents

Portfolio Analysis Workflow

Chat with agent: "I need a complete analysis of my tech portfolio: analyze risk, optimize allocation, and provide investment recommendations."

Agents will coordinate automatically to provide comprehensive analysis

🔧 Available Tools

Tool	Description
create_agent	Create a new specialized agent
list_agents	View all saved agents
chat_with_agent	Interact with specific agents
delete_agent	Remove an agent permanently
create_finance_team	Generate complete financial analysis team
get_conversation_history	View chat history and agent transfers
reset_conversation	Clear conversation history

📁 Project Structure

claude-swarm-mcp/
├── claude_swarm.py              # Core Swarm framework
├── claude_swarm_mcp_server.py   # MCP server implementation
├── requirements.txt             # Python dependencies
├── README.md                    # This file
├── LICENSE                      # MIT License
├── examples/                    # Usage examples
│   ├── finance_workflow.py      # Financial analysis example
│   ├── customer_service.py      # Customer service template
│   └── research_team.py         # Research coordination example
├── tests/                       # Test suite
│   ├── test_agents.py           # Agent functionality tests
│   ├── test_mcp_server.py       # MCP server tests
│   └── test_swarm.py           # Swarm coordination tests
└── docs/                       # Documentation
    ├── API.md                   # API reference
    ├── DEPLOYMENT.md            # Deployment guide
    └── CONTRIBUTING.md          # Contribution guidelines

🏗️ Architecture

Core Components

1. Claude Swarm Framework (claude_swarm.py)

   • Multi-agent orchestration
   • Automatic handoffs between agents
   • Shared conversation context
   • Function calling integration

2. MCP Server (claude_swarm_mcp_server.py)

   • Model Context Protocol implementation
   • Persistent agent storage
   • Tool registration and handling
   • Claude Desktop integration

3. Agent Storage (data/)

   • JSON-based agent persistence
   • Conversation history
   • Context variables
   • Backup and restore capabilities

Data Flow

Claude Desktop ↔ MCP Protocol ↔ Swarm Server ↔ Claude API
                                      ↓
                              Agent Storage (JSON)

🎨 Use Cases

Financial Services

• Portfolio Risk Analysis: VaR calculations, stress testing
• Investment Research: Market analysis, stock recommendations
• Compliance Monitoring: Regulatory requirements, position limits
• Client Advisory: Personalized investment advice

Customer Support

• Intelligent Triage: Route customers to appropriate specialists
• Multi-language Support: Automatic language detection and routing
• Escalation Management: Seamless handoffs to senior agents
• Knowledge Base Integration: Context-aware information retrieval

Research & Development

• Literature Review: Coordinate research across multiple domains
• Data Analysis: Statistical analysis, visualization, reporting
• Project Management: Task coordination, milestone tracking
• Technical Documentation: Automated documentation generation

🔒 Security & Privacy

• Local Storage: All data stored locally on your machine
• API Key Security: Secure API key handling through environment variables
• No External Dependencies: No third-party services for agent storage
• Audit Trail: Complete conversation history and agent interactions

🛠️ Configuration

Environment Variables

export ANTHROPIC_API_KEY="your-api-key"
export CLAUDE_SWARM_STORAGE_DIR="/custom/storage/path"  # Optional
export CLAUDE_SWARM_DEBUG="true"  # Optional debug mode

Storage Configuration

# Custom storage location
storage_path = "/Users/yourname/claude_agents"
server = ClaudeSwarmMCPServer(storage_dir=storage_path)

📊 Performance

• Agent Creation: < 2 seconds
• Chat Response: 3-8 seconds (depending on complexity)
• Agent Handoffs: < 1 second
• Storage Operations: < 500ms
• Memory Usage: ~50-100MB (depending on conversation history)

🔍 Troubleshooting

Common Issues

1. API Authentication Errors

# Check your API key
python3 -c "from anthropic import Anthropic; print('API key valid')"

2. MCP Connection Issues

• Restart Claude Desktop
• Check server logs for errors
• Verify config file path and syntax

3. Agent Not Responding

• Check billing status in Anthropic Console
• Verify agent instructions are clear
• Test with simple messages first

4. Storage Permission Errors

# Fix permissions
chmod 755 /path/to/storage/directory

Debug Mode

# Run server with debug logging
CLAUDE_SWARM_DEBUG=true python3 claude_swarm_mcp_server.py

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone and setup development environment
git clone https://github.com/yourusername/claude-swarm-mcp.git
cd claude-swarm-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt

Running Tests

python -m pytest tests/ -v

📈 Roadmap

• Advanced Agent Coordination: Complex multi-step workflows
• Custom Function Registry: User-defined agent capabilities
• Web UI: Browser-based agent management interface
• Integration Templates: Pre-built integrations for popular services
• Performance Optimization: Faster response times and memory usage
• Multi-Model Support: Support for other LLM providers
• Cloud Deployment: Docker containers and cloud hosting options

📄 License

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

🙏 Acknowledgments

• Anthropic for Claude AI and excellent API
• OpenAI for the original Swarm framework inspiration
• Model Context Protocol team for the MCP specification
• Claude Desktop team for seamless integration

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

---

⭐ Star this repository if you find it useful!

Built with ❤️ for the Claude AI community# Claude Swarm MCP Server

A Model Context Protocol (MCP) server that enables multi-agent orchestration using Claude AI through Claude Desktop. Create, manage, and coordinate specialized AI agents for complex workflows like financial analysis, customer service, and research.

🚀 Features

• 🤖 Persistent Agents: Create specialized Claude agents that survive restarts
• 🔄 Agent Coordination: Intelligent handoffs between agents based on expertise
• 💾 Local Storage: All agents and conversations saved locally
• 📊 Pre-built Templates: Ready-to-use financial analysis and customer service teams
• 🎯 Specialized Functions: Custom tools and capabilities per agent
• 🔧 Easy Integration: Works seamlessly with Claude Desktop

📋 Quick Start

Prerequisites

• Python 3.10+
• Claude Desktop installed
• Anthropic API key with billing enabled

Installation

1. Clone the repository

git clone https://github.com/yourusername/claude-swarm-mcp.git
cd claude-swarm-mcp

2. Install dependencies

pip install -r requirements.txt

3. **Configure# Claude Swarm MCP Server

A Model Context Protocol (MCP) server that enables multi-agent orchestration using Claude AI through Claude Desktop. Create, manage, and coordinate specialized AI agents for complex workflows like financial analysis, customer service, and research.

🚀 Features

• 🤖 Persistent Agents: Create specialized Claude agents that survive restarts
• 🔄 Agent Coordination: Intelligent handoffs between agents based on expertise
• 💾 Local Storage: All agents and conversations saved locally
• 📊 Pre-built Templates: Ready-to-use financial analysis and customer service teams
• 🎯 Specialized Functions: Custom tools and capabilities per agent
• 🔧 Easy Integration: Works seamlessly with Claude Desktop

📋 Quick