Remote OpenClaw
Menu

Rundeck MCP Server

dinfiesta/rundeck-mcp
1 starsMITCommunity

Install to Claude Code

This server doesn't publish a one-line install command. Follow the setup in the source repository.

Summary

Enables AI assistants to manage Rundeck automation platform, including project and job management, execution, and system monitoring through the MCP protocol.

README.md

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"
  1. 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 ```bash

Check logs

docker logs rundeck-mcp-server

Restart container

docker restart rundeck-mcp-server ```

Rundeck Connection Failed ```bash

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: ```bash

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

Related MCP servers

Browse all →

Axiom MCP

axiomhq/mcp-server-axiom

61 starsOpen

Grafana MCP

grafana/mcp-grafana

3,180 starsOpen

Sentry MCP

getsentry/sentry-mcp

741 starsOpen

Apify MCP

apify/actors-mcp-server

Browser & ScrapingOpen

AWS MCP Servers

awslabs/mcp

9,330 starsOpen

Azure MCP

Azure/azure-mcp

1,219 starsOpen

Browse

MCP servers by category

Other2643AI & ML2284Search2091Developer Tools1127Vector & Memory1121Cloud & DevOps721Files & Docs719Databases704Finance & Payments701Browser & Scraping485Communication418Productivity355