Rundeck MCP Server

A Model Context Protocol (MCP) server that provides seamless integration between AI assistants and Rundeck automation platform. This server exposes 9 comprehensive Rundeck tools through the MCP protocol, enabling AI assistants to interact with Rundeck servers in real-time.

🚀 Features

9 Rundeck Tools: Complete set of tools for Rundeck management
Real-time Data: Live connection to Rundeck API
Docker Integration: Containerized deployment with Rundeck
Kubernetes Ready: Production-grade K8s manifests with NetworkPolicies
MCP Protocol: Standard interface for AI assistant integration
AI Assistant Compatible: Works with any MCP-compatible AI assistant
Production Ready: Tested and verified working integration

📋 Available Tools

| Tool | Description | |------|-------------| | get_rundeck_system_info | Get server status, version, memory, CPU stats | | list_rundeck_projects | List all available Rundeck projects | | list_rundeck_jobs | List jobs in a specific project | | get_rundeck_job | Get detailed job information | | execute_rundeck_job | Execute jobs with optional arguments | | get_rundeck_execution | Get execution status and details | | list_rundeck_job_executions | View job execution history | | analyze_rundeck_job_performance | Performance analytics for jobs | | abort_rundeck_execution | Stop running job executions |

🏗️ Architecture

┌─────────────┐    MCP Protocol    ┌──────────────┐    Rundeck API    ┌─────────────┐
│ AI Assistant│◄──────────────────►│  MCP Server  │◄─────────────────►│   Rundeck   │
│             │                    │   (Docker)   │                   │   Server    │
└─────────────┘                    └──────────────┘                   └─────────────┘

🐳 Quick Start

Option 1: Docker Compose (Recommended for Development)

# Clone and navigate to directory
git clone <repository>
cd rundeck-mcp

# Set your Rundeck API token
echo "RUNDECK_API_TOKEN=YOUR_RUNDECK_API_TOKEN_HERE" > .env

# Deploy containers
docker-compose up -d

# Check status
docker-compose ps

Option 2: Kubernetes (Recommended for Production)

# Clone and navigate to directory
git clone <repository>
cd rundeck-mcp

# Update API token in k8s/secret.yaml
echo -n "your-actual-token" | base64
# Replace the value in k8s/secret.yaml

# Deploy to Kubernetes
./k8s/deploy.sh

# Or with specific network policy mode
NETWORK_POLICY_MODE=strict ./k8s/deploy.sh

☸️ Kubernetes Deployment

Quick Deploy

# Standard deployment
./k8s/deploy.sh

# Strict security mode
NETWORK_POLICY_MODE=strict ./k8s/deploy.sh

# With monitoring support
NETWORK_POLICY_MODE=monitoring ./k8s/deploy.sh

Network Policy Modes

| Mode | Description | Use Case | |------|-------------|----------| | standard | Basic network isolation with external access | Development/Testing | | strict | Maximum security, minimal network access | High-security environments | | monitoring | Standard + monitoring namespace access | Production with observability |

Kubernetes Resources

| Resource | Description | |----------|-------------| | namespace.yaml | Dedicated rundeck-mcp namespace | | configmap.yaml | Non-sensitive configuration | | secret.yaml | API tokens and sensitive data | | pvc.yaml | Persistent storage for Rundeck data | | rundeck-deployment.yaml | Rundeck server deployment | | rundeck-service.yaml | ClusterIP + NodePort services | | mcp-deployment.yaml | MCP server deployment | | ingress.yaml | External access via Ingress | | network-policy*.yaml | Network security policies |

Access Methods

# NodePort (immediate access)
http://localhost:30440

# Port-forward (secure tunnel)
kubectl port-forward service/rundeck-service 4440:4440 -n rundeck-mcp

# Ingress (with DNS setup)
http://rundeck.local

Useful Commands

# Check deployment status
kubectl get pods -n rundeck-mcp

# View logs
kubectl logs -f deployment/rundeck -n rundeck-mcp
kubectl logs -f deployment/rundeck-mcp-server -n rundeck-mcp

# Check network policies
kubectl get networkpolicies -n rundeck-mcp

# Scale deployments
kubectl scale deployment rundeck --replicas=2 -n rundeck-mcp

# Cleanup
./k8s/cleanup.sh

2. Configure MCP Client

For Kiro IDE

Create .kiro/settings/mcp.json in your workspace:

{
  "mcpServers": {
    "rundeck": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=rundeck-mcp_rundeck-network",
        "-e", "RUNDECK_URL=http://rundeck:4440",
        "-e", "RUNDECK_API_TOKEN=admin_token_change_me",
        "-e", "RUNDECK_API_VERSION=50",
        "-e", "PYTHONUNBUFFERED=1",
        "rundeck-mcp-rundeck-mcp"
      ],
      "disabled": false,
      "autoApprove": [
        "list_projects",
        "list_jobs",
        "get_job",
        "get_execution",
        "list_job_executions",
        "analyze_job_performance",
        "get_system_info"
      ]
    }
  }
}

Note: Environment variables (RUNDECK_URL, RUNDECK_API_TOKEN, etc.) are automatically loaded from the Docker container's environment, so you don't need to specify them in the MCP configuration.

For Other MCP-Compatible Clients

{
  "mcpServers": {
    "rundeck": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=rundeck-mcp_rundeck-network",
        "-e", "RUNDECK_URL=http://rundeck:4440",
        "-e", "RUNDECK_API_TOKEN=admin_token_change_me",
        "-e", "RUNDECK_API_VERSION=50",
        "-e", "PYTHONUNBUFFERED=1",
        "rundeck-mcp-rundeck-mcp"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

3. Test the Integration

Using Kiro IDE

Once the MCP server is configured, you can use the Rundeck MCP tools directly:

# List available MCP tools
mcp_rundeck_list_projects
mcp_rundeck_list_jobs
mcp_rundeck_get_system_info

Or ask Kiro naturally:

"Get my Rundeck system information"
"List my Rundeck projects"
"Show me jobs in the TRIVAGO project"
"Execute the TEST job"

Using Other MCP Clients

Using your MCP-compatible AI assistant, ask:

"Get my Rundeck system information"
"List my Rundeck projects"
"Show me job execution history"

📁 Project Structure

rundeck-mcp/
├── rundeck_mcp_server.py    # Main MCP server implementation
├── docker-compose.yml       # Docker services configuration
├── Dockerfile              # Container build configuration
├── entrypoint.sh           # Container startup script
├── requirements.txt        # Python dependencies
├── .env                    # Environment variables
├── k8s/                    # Kubernetes deployment manifests
│   ├── deploy.sh           # Automated deployment script
│   ├── cleanup.sh          # Cleanup script
│   ├── namespace.yaml      # Kubernetes namespace
│   ├── configmap.yaml      # Configuration data
│   ├── secret.yaml         # Sensitive data (API tokens)
│   ├── pvc.yaml            # Persistent volume claims
│   ├── rundeck-deployment.yaml    # Rundeck server deployment
│   ├── rundeck-service.yaml       # Rundeck services
│   ├── mcp-deployment.yaml        # MCP server deployment
│   ├── ingress.yaml               # External access
│   ├── network-policy.yaml        # Standard network policies
│   ├── network-policy-strict.yaml # Strict security policies
│   └── network-policy-monitoring.yaml # Monitoring support
└── README.md              # This file

🔧 Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | RUNDECK_URL | Rundeck server URL | http://rundeck:4440 | | RUNDECK_API_TOKEN | Rundeck API authentication token | Required | | RUNDECK_API_VERSION | Rundeck API version | 50 |

Docker Services

| Service | Port | Description | |---------|------|-------------| | rundeck | 4440 | Rundeck server web interface | | rundeck-mcp | - | MCP server (internal) |

🧪 Testing & Verification

✅ Verified Working Integration

The integration has been tested and verified working with:

Kiro IDE: Full MCP integration with Docker-based server
Rundeck: 5.8.0-20241205
API Version: 50
MCP Protocol: Compatible with MCP-enabled AI assistants
Real-time Data: Live system information retrieval
Docker: Containerized deployment with automatic environment configuration
Kubernetes: Production-ready deployment with NetworkPolicies

Test MCP Server Connection

# Check container status
docker-compose ps

# View MCP server logs
docker logs rundeck-mcp-server

# Test Rundeck connectivity
docker exec rundeck-mcp-server python3 -c "
import asyncio, os
from rundeck_mcp_server import RundeckMCPServer
os.environ['RUNDECK_URL'] = 'http://rundeck:4440'
os.environ['RUNDECK_API_TOKEN'] = 'YOUR_RUNDECK_API_TOKEN_HERE'
os.environ['RUNDECK_API_VERSION'] = '50'
server = RundeckMCPServer()
print(asyncio.run(server.get_system_info()))
"

Test with Kiro IDE

Ensure Docker containers are running: docker-compose ps
Open Kiro IDE in the project directory
Verify MCP configuration is loaded in .kiro/settings/mcp.json

Use MCP tools directly:

mcp_rundeck_get_system_info
mcp_rundeck_list_projects
mcp_rundeck_list_jobs project="TRIVAGO"

Or ask Kiro: "Get my Rundeck system information"

Test with Other AI Assistants

Open your MCP-compatible AI assistant
Ensure MCP configuration is loaded
Ask: "Get my Rundeck system information"
Verify real-time data is returned

Expected Output

{
  "system": {
    "rundeck": {
      "version": "5.8.0-20241205",
      "apiversion": "50",
      "build": "5.8.0-20241205",
      "serverUUID": "a14bc3e6-75e8-4fe4-a90d-a16dcc976bf6"
    },
    "stats": {
      "memory": {
        "free": 428099752,
        "total": 918552576,
        "unit": "byte"
      },
      "cpu": {
        "processors": 12,
        "loadAverage": {
          "average": 0,
          "unit": "percent"
        }
      }
    },
    "os": {
      "name": "Linux",
      "version": "6.10.14-linuxkit",
      "arch": "amd64"
    }
  }
}

🔍 Troubleshooting

Common Issues

MCP Server Not Starting

# Check logs
docker logs rundeck-mcp-server

# Restart container
docker restart rundeck-mcp-server

Rundeck Connection Failed

# Verify Rundeck is running
curl http://localhost:4440

# Check API token
docker exec rundeck-mcp-server env | grep RUNDECK

AI Assistant MCP Not Working

Verify MCP configuration file exists (.kiro/settings/mcp.json for Kiro)
Check MCP server logs in your AI assistant
Restart AI assistant to reload MCP configuration
For Kiro: Check the MCP Server view in the feature panel

Health Checks

# Container health
docker-compose ps

# Rundeck health
curl http://localhost:4440/api/50/system/info

# MCP server process
docker exec rundeck-mcp-server ps aux | grep python

📊 Performance

Memory Usage: ~50MB per container
Response Time: <2 seconds for most operations
Concurrent Requests: Supports multiple simultaneous MCP calls
API Rate Limits: Respects Rundeck API throttling

🔐 Security

API tokens stored in environment variables
Container network isolation
No external ports exposed for MCP server
Rundeck authentication required

🚀 Production Deployment

Resource Requirements

CPU: 1 core minimum
Memory: 2GB minimum (1GB Rundeck + 1GB overhead)
Storage: 5GB for logs and data
Network: Internal container networking

Scaling Considerations

Single MCP server instance per Rundeck server
Multiple AI assistant instances can connect to same MCP server
Rundeck handles concurrent API requests

📝 API Reference

System Information

# Get comprehensive system status
await server.get_system_info()

Project Management

# List all projects
await server.list_projects()

# List jobs in project
await server.list_jobs("project-name")

Job Execution

# Execute job
await server.execute_job("job-id", {"param": "value"})

# Check execution status
await server.get_execution("execution-id")

🎯 Example Usage with AI Assistant

With Kiro IDE

Once configured, you can use both direct MCP tool calls and natural language:

Direct MCP Tool Usage:

# Get system information
mcp_rundeck_get_system_info

# List projects  
mcp_rundeck_list_projects

# List jobs in a project
mcp_rundeck_list_jobs project="TRIVAGO"

# Execute a job
mcp_rundeck_execute_job job_id="5a2584fb-d01f-496b-a035-830940b53025"

Natural Language with Kiro:

You: "Get my Rundeck system information"
Kiro: [Calls mcp_rundeck_get_system_info]
      "Your Rundeck server is version 5.8.0-20241205, running on Linux 
       with 12 CPU cores and 408 MB free memory..."

You: "List my Rundeck projects"  
Kiro: [Calls mcp_rundeck_list_projects]
      "You currently have 1 project configured: TRIVAGO project created on
       December 20, 2025"

You: "Show me jobs in the TRIVAGO project"
Kiro: [Calls mcp_rundeck_list_jobs with project="TRIVAGO"]
      "Found 1 job in TRIVAGO project: TEST job (ID: 5a2584fb-d01f-496b-a035-830940b53025)
       in the TEST group, currently enabled and scheduled"

With Other MCP Clients

Once configured, you can use natural language with your AI assistant:

You: "Get my Rundeck system information"
AI: [Calls get_rundeck_system_info via MCP]
    "Your Rundeck server is version 5.8.0-20241205, running on Linux 
     with 12 CPU cores and 408 MB free memory..."

You: "List my Rundeck projects"  
AI: [Calls list_rundeck_projects via MCP]
    "You currently have 1 project configured: TRIVAGO project created on
     December 20, 2025"

You: "What's the server uptime?"
AI: [Calls get_rundeck_system_info via MCP]
    "Your Rundeck server has been running for 2.6 minutes, started at
     15:47:29 UTC"

🤝 Contributing

Fork the repository
Create feature branch
Test with Docker deployment
Submit pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

Issues: GitHub Issues
Documentation: This README
Testing: Use provided test commands

Status: ✅ Production Ready & Verified Working
Last Updated: December 2025
Version: 1.0.0
Tested With: MCP-compatible AI assistants, Rundeck 5.8.0, MCP Protocol
Created By: dinfiesta@gmail.com