# rundeck-mcp-server

[![npm version](https://img.shields.io/npm/v/rundeck-mcp-server.svg)](https://www.npmjs.com/package/rundeck-mcp-server)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

The most comprehensive [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for [Rundeck](https://www.rundeck.com). Manage jobs, executions, projects, nodes, and more from Claude, Cursor, or any MCP-compatible client.

**50 tools** across 7 domains — full CRUD operations, execution monitoring, and system management.

## Features

- **Projects** — List, create, delete, and configure projects
- **Jobs** — List, create, run, retry, import/export, enable/disable execution and scheduling
- **Executions** — Monitor running jobs, get logs, abort executions, query history
- **Nodes** — Browse node inventory with filter expressions
- **System** — Server info, health checks, metrics, execution mode control
- **Key Storage** — Manage secrets, passwords, and SSH keys
- **Webhooks** — Create and manage webhook triggers
- **ACL Policies** — Full CRUD for system access control policies

## Quick Start

### Prerequisites

- Node.js 18+
- A Rundeck instance with API access
- A Rundeck API token ([how to generate one](https://docs.rundeck.com/docs/manual/10-user.html#user-api-tokens))

### Using with Claude Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "rundeck": {
      "command": "npx",
      "args": ["-y", "rundeck-mcp-server"],
      "env": {
        "RUNDECK_URL": "http://your-rundeck-server:4440",
        "RUNDECK_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Using with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rundeck": {
      "command": "npx",
      "args": ["-y", "rundeck-mcp-server"],
      "env": {
        "RUNDECK_URL": "http://your-rundeck-server:4440",
        "RUNDECK_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Using with Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "rundeck": {
      "command": "npx",
      "args": ["-y", "rundeck-mcp-server"],
      "env": {
        "RUNDECK_URL": "http://your-rundeck-server:4440",
        "RUNDECK_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Configuration

| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `RUNDECK_URL` | Yes | — | Rundeck server URL (e.g., `http://localhost:4440`) |
| `RUNDECK_API_TOKEN` | Yes | — | API token for authentication |
| `RUNDECK_API_VERSION` | No | `41` | Rundeck API version |
| `RUNDECK_TIMEOUT` | No | `30000` | Request timeout in milliseconds |

## Available Tools

### Projects (6 tools)

| Tool | Description |
|------|-------------|
| `rundeck_list_projects` | List all projects |
| `rundeck_get_project` | Get project details and configuration |
| `rundeck_create_project` | Create a new project |
| `rundeck_delete_project` | Delete a project permanently |
| `rundeck_get_project_config` | Get project configuration properties |
| `rundeck_set_project_config` | Update project configuration |

### Jobs (14 tools)

| Tool | Description |
|------|-------------|
| `rundeck_list_jobs` | List jobs with filtering by group, name, tags |
| `rundeck_get_job` | Get full job definition (steps, options, schedule) |
| `rundeck_get_job_metadata` | Get job metadata (author, dates) |
| `rundeck_run_job` | Execute a job with options and node filters |
| `rundeck_retry_job` | Retry a failed execution |
| `rundeck_import_jobs` | Import jobs from JSON/YAML/XML |
| `rundeck_export_jobs` | Export job definitions |
| `rundeck_delete_job` | Delete a job |
| `rundeck_bulk_delete_jobs` | Delete multiple jobs at once |
| `rundeck_enable_job_execution` | Enable job execution |
| `rundeck_disable_job_execution` | Disable job execution |
| `rundeck_enable_job_schedule` | Enable job scheduling |
| `rundeck_disable_job_schedule` | Disable job scheduling |
| `rundeck_get_job_forecast` | Get upcoming scheduled execution times |

### Executions (8 tools)

| Tool | Description |
|------|-------------|
| `rundeck_list_executions` | Query executions with status and time filters |
| `rundeck_list_running_executions` | List currently running executions |
| `rundeck_get_execution` | Get execution details (status, duration, nodes) |
| `rundeck_get_execution_output` | Get execution log output |
| `rundeck_abort_execution` | Abort a running execution |
| `rundeck_get_job_executions` | List execution history for a job |
| `rundeck_delete_job_executions` | Delete all executions for a job |
| `rundeck_bulk_delete_executions` | Delete multiple executions by ID |

### Nodes (2 tools)

| Tool | Description |
|------|-------------|
| `rundeck_list_nodes` | List nodes with filter expressions |
| `rundeck_get_node` | Get node details |

### System (12 tools)

| Tool | Description |
|------|-------------|
| `rundeck_system_info` | Server version, uptime, and system stats |
| `rundeck_get_execution_mode` | Check active/passive execution mode |
| `rundeck_set_execution_mode` | Enable or disable executions system-wide |
| `rundeck_get_metrics` | Server performance metrics |
| `rundeck_healthcheck` | System health check |
| `rundeck_list_users` | List all users |
| `rundeck_get_log_storage` | Log storage status |
| `rundeck_list_acl_policies` | List ACL policy files |
| `rundeck_get_acl_policy` | Get ACL policy content |
| `rundeck_create_acl_policy` | Create ACL policy |
| `rundeck_update_acl_policy` | Update ACL policy |
| `rundeck_delete_acl_policy` | Delete ACL policy |

### Key Storage (4 tools)

| Tool | Description |
|------|-------------|
| `rundeck_list_keys` | Browse key storage tree |
| `rundeck_get_key_metadata` | Get key metadata (not the secret value) |
| `rundeck_create_key` | Store a password, public key, or private key |
| `rundeck_delete_key` | Delete a stored key |

### Webhooks (4 tools)

| Tool | Description |
|------|-------------|
| `rundeck_list_webhooks` | List webhooks in a project |
| `rundeck_get_webhook` | Get webhook details |
| `rundeck_create_webhook` | Create a webhook trigger |
| `rundeck_delete_webhook` | Delete a webhook |

## Usage Examples

Once configured, you can interact with Rundeck using natural language:

- *"List all projects in Rundeck"*
- *"Show me the running executions in the production project"*
- *"Run the deploy-app job in the staging project with version=2.1.0"*
- *"Get the logs from execution 1234"*
- *"Abort execution 5678"*
- *"Show me all failed executions in the last 24 hours"*
- *"List the nodes tagged as 'web' in the production project"*
- *"Check the Rundeck server health"*
- *"Disable the cleanup job schedule"*

## Development

```bash
# Clone the repository
git clone https://github.com/mariomorenodev/rundeck-mcp-server.git
cd rundeck-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
RUNDECK_URL=http://localhost:4440 RUNDECK_API_TOKEN=your-token npm run dev
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details.