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

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

   mcp_rundeck_get_system_info
   mcp_rundeck_list_projects
   mcp_rundeck_list_jobs project="TRIVAGO"
   

5. Or ask Kiro: "Get my Rundeck system information"

Test with Other AI Assistants

1. Open your MCP-compatible AI assistant
2. Ensure MCP configuration is loaded
3. Ask: "Get my Rundeck system information"
4. 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

1. Verify MCP configuration file exists (.kiro/settings/mcp.json for Kiro)
2. Check MCP server logs in your AI assistant
3. Restart AI assistant to reload MCP configuration
4. 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

1. Fork the repository
2. Create feature branch
3. Test with Docker deployment
4. 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