Roo Code Setup

Roo Code MCP Setup

Connect automagik-tools to Roo Code, the AI-powered coding assistant. Get instant API access in your development workflow.

Prerequisites

Install Roo Code

Download and install Roo Code from roocode.dev

Install automagik-tools

# Option 1: pip
pip install automagik-tools

# Option 2: uvx (instant, no install)
uvx automagik-tools --version

Get API Credentials

For the tools you’ll use:

# Example: OpenAI (for Genie)
export OPENAI_API_KEY=sk-your-key

# Example: Evolution API (WhatsApp)
export EVOLUTION_API_KEY=your-key
export EVOLUTION_API_BASE_URL=https://your-instance.com

Configuration

Option 1: Genie (Universal Orchestrator)

Open Roo Code Settings

Click the Roo icon in your editor
Navigate to Settings or Preferences
Find MCP Servers section

Add Genie MCP Server

Click Add Server and configure:

{
  "name": "genie",
  "command": "uvx",
  "args": [
    "automagik-tools@latest",
    "tool",
    "genie"
  ],
  "env": {
    "OPENAI_API_KEY": "sk-your-openai-key-here"
  }
}

Genie is a universal orchestrator that can handle multiple API requests intelligently. It uses OpenAI to coordinate complex workflows.

Save and Restart

Save the configuration
Restart Roo Code for changes to take effect

Test

In Roo Code’s chat, try:

"Help me orchestrate a complex workflow"

Roo should use the Genie tool via MCP!

Option 2: WhatsApp via Evolution API

Connect WhatsApp for messaging automation.

Setup Evolution API

First, ensure you have Evolution API running. See Evolution API docs for setup.

Configure MCP Server

{
  "name": "whatsapp",
  "command": "uvx",
  "args": [
    "automagik-tools@latest",
    "tool",
    "evolution-api"
  ],
  "env": {
    "EVOLUTION_API_KEY": "your-evolution-api-key",
    "EVOLUTION_API_BASE_URL": "https://your-instance.com"
  }
}

Test WhatsApp

In Roo Code:

"Send a WhatsApp message to +1234567890: Hello from Roo Code!"

Option 3: Custom API via OpenAPI

Convert any OpenAPI spec into MCP tools.

{
  "name": "petstore",
  "command": "uvx",
  "args": [
    "automagik-tools@latest",
    "openapi",
    "https://petstore3.swagger.io/api/v3/openapi.json"
  ]
}

Replace the PetStore URL with your own OpenAPI specification URL. This works with any API that has an OpenAPI/Swagger spec.

See Custom OpenAPI guide for details.

Option 4: Multiple Tools

Connect multiple tools simultaneously.

{
  "mcpServers": [
    {
      "name": "genie",
      "command": "uvx",
      "args": ["automagik-tools@latest", "tool", "genie"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key"
      }
    },
    {
      "name": "whatsapp",
      "command": "uvx",
      "args": ["automagik-tools@latest", "tool", "evolution-api"],
      "env": {
        "EVOLUTION_API_KEY": "your-key",
        "EVOLUTION_API_BASE_URL": "https://your-instance.com"
      }
    },
    {
      "name": "custom-api",
      "command": "uvx",
      "args": [
        "automagik-tools@latest",
        "openapi",
        "https://api.example.com/openapi.json"
      ]
    }
  ]
}

Available Real Tools

These are the ONLY tools available in automagik-tools. Verify by running:

uvx automagik-tools list

Tool	Description	Required Env Vars
genie	Universal orchestrator	`OPENAI_API_KEY`
evolution-api	WhatsApp messaging	`EVOLUTION_API_KEY`, `EVOLUTION_API_BASE_URL`
omni	Multi-channel messaging	Varies by channel
automagik	Core automation	None
spark	Task automation	None
automagik-hive	Distributed tasks	None
gemini-assistant	Gemini integration	`GOOGLE_API_KEY`
OpenAPI	Custom API conversion	API-specific

Usage in Roo Code

Orchestration with Genie

You: "Plan a multi-step workflow to process data and send notifications"

Roo: [Uses genie tool via MCP]

Roo: "I've planned the workflow:
     1. Data validation and cleaning
     2. Processing pipeline setup
     3. Notification triggers configured

     Would you like me to execute this plan?"

WhatsApp Automation

You: "Send a WhatsApp message to the team with today's deployment status"

Roo: [Uses evolution-api tool via MCP]

Roo: "Message sent via WhatsApp:

     ✅ Deployment Status - January 4, 2025
     - API: Deployed successfully
     - Database: Migration complete
     - Frontend: Live on production

     All systems operational!"

Custom API Integration

You: "Create a new pet in the PetStore API"

Roo: [Uses petstore OpenAPI tool via MCP]

Roo: "Created pet:
     - ID: 12345
     - Name: Fluffy
     - Status: Available

     API response successful!"

Authentication Setup

OpenAI API Key (for Genie)

Get API Key

Visit https://platform.openai.com/api-keys

Click Create new secret key
Name it “Roo Code Genie Integration”
Copy the key (starts with sk-)

Add to Roo Config

{
  "env": {
    "OPENAI_API_KEY": "sk-your-key-here"
  }
}

Evolution API Setup (for WhatsApp)

Deploy Evolution API

Follow the Evolution API installation guide

Get Credentials

Get your API key from Evolution API dashboard
Note your instance URL

Add to Roo Config

{
  "env": {
    "EVOLUTION_API_KEY": "your-key",
    "EVOLUTION_API_BASE_URL": "https://your-instance.com"
  }
}

Troubleshooting

MCP server not connecting

Error: Failed to connect to MCP serverSolutions:

Verify automagik-tools installation:

uvx automagik-tools --version
# Should output version number

Check tool exists:
```
uvx automagik-tools list
```
Verify configuration syntax (valid JSON)
Ensure "command": "uvx" not "node" or "python"
Restart Roo Code completely

Authentication failures

Error: 401 Unauthorized or 403 ForbiddenSolutions:

Verify API keys are correct and not expired
Check environment variable names match exactly

Test credentials manually:

# OpenAI
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

# Evolution API
curl -H "apikey: $EVOLUTION_API_KEY" \
  $EVOLUTION_API_BASE_URL/instance/fetchInstances

Tools not appearing

Symptom: Roo doesn’t seem to have access to toolsSolutions:

Ask Roo: “What MCP tools do you have access to?”
Verify the tool name from uvx automagik-tools list
Check for configuration errors in logs
Ensure proper restart after config changes
Try removing and re-adding the server

Wrong tool configured

Error: Tool not found or doesn’t existSolution: Only use tools from this verified list:

uvx automagik-tools list

Output shows:

genie
evolution-api
omni
automagik
spark
automagik-hive
gemini-assistant

Any other tool name will fail!

Configuration File Location

Roo Code typically stores MCP configuration in:

macOS
Windows
Linux

~/Library/Application Support/Roo/config.json

Or access via: Roo Settings → MCP Servers → Edit Config

Best Practices

Use environment variables for sensitive credentials:

# Add to ~/.bashrc or ~/.zshrc
export OPENAI_API_KEY=sk-xxx
export EVOLUTION_API_KEY=your-key
export EVOLUTION_API_BASE_URL=https://your-instance.com

Then reference in config:

{
  "env": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}"
  }
}

Verify tool names before configuring:

# Always run this first
uvx automagik-tools list

# Then use exact names from output

Test tools independently before using in Roo:

# Test Genie
uvx automagik-tools tool genie --help

# Test Evolution API
uvx automagik-tools tool evolution-api --help

Use descriptive server names for better organization:

{
  "mcpServers": [
    {"name": "genie-orchestrator", ...},
    {"name": "whatsapp-production", ...},
    {"name": "api-staging", ...}
  ]
}

Next Steps

Integration Overview

Learn about MCP integration

Custom OpenAPI

Generate tools from your API

Available Tools

Complete list of real tools

CLI Reference

Command line usage

Phase 1: Get It Running

Phase 2: Reference

Phase 3: Real Examples

Phase 4: Deep Concepts

Troubleshooting

Roo Code MCP Setup

Prerequisites

Configuration

Option 1: Genie (Universal Orchestrator)

Option 2: WhatsApp via Evolution API

Option 3: Custom API via OpenAPI

Option 4: Multiple Tools

Available Real Tools

Usage in Roo Code

Orchestration with Genie

WhatsApp Automation

Custom API Integration

Authentication Setup

OpenAI API Key (for Genie)

Evolution API Setup (for WhatsApp)

Troubleshooting

Configuration File Location

Best Practices

Next Steps

Integration Overview

Custom OpenAPI

Available Tools

CLI Reference

Phase 1: Get It Running

Phase 2: Reference

Phase 3: Real Examples

Phase 4: Deep Concepts

Troubleshooting

​Roo Code MCP Setup

​Prerequisites

​Configuration

​Option 1: Genie (Universal Orchestrator)

​Option 2: WhatsApp via Evolution API

​Option 3: Custom API via OpenAPI

​Option 4: Multiple Tools

​Available Real Tools

​Usage in Roo Code

​Orchestration with Genie

​WhatsApp Automation

​Custom API Integration

​Authentication Setup

​OpenAI API Key (for Genie)

​Evolution API Setup (for WhatsApp)

​Troubleshooting

​Configuration File Location

​Best Practices

​Next Steps

Integration Overview

Custom OpenAPI

Available Tools

CLI Reference

Roo Code MCP Setup

Prerequisites

Configuration

Option 1: Genie (Universal Orchestrator)

Option 2: WhatsApp via Evolution API

Option 3: Custom API via OpenAPI

Option 4: Multiple Tools

Available Real Tools

Usage in Roo Code

Orchestration with Genie

WhatsApp Automation

Custom API Integration

Authentication Setup

OpenAI API Key (for Genie)

Evolution API Setup (for WhatsApp)

Troubleshooting

Configuration File Location

Best Practices

Next Steps