Content
# rundeck-mcp-server
[](https://www.npmjs.com/package/rundeck-mcp-server)
[](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.
