dokku-mcp
This server lets MCP clients (Cursor, Claude Desktop, etc.) inspect and manage a Dokku host over SSH with structured tools, read-only defaults, and explicit confirmation guardrails.
List apps:
list_apps— see all apps, respecting allow/deny lists.Inspect app status:
app_report— running state, scale, processes viaps:report.View config:
app_config— see env vars, secrets masked unlessreveal_secrets=True.Read logs:
app_logs— fetch recent logs (default 50, max 500 lines).Check domains:
app_domains— domain/VHOST report.Derive URLs:
app_url— public HTTPS URLs from domains.Create apps:
create_app— requiresDOKKU_MCP_MODE=read-write, validates app names.Set config:
set_config— set env vars, requires read-write +confirm=True; values never echoed.Restart apps:
restart_app— requires read-write +confirm=True.Scale apps:
scale_app— change process counts (e.g. web=2), requires read-write +confirm=True.
No free-form shell access and no destroy_app are exposed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dokku-mcp Is api running, and what's its public URL?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
dokku-mcp
FastMCP server that lets Cursor, Claude Desktop, and other MCP clients inspect and manage a Dokku host over SSH — structured tools, shared session, read-only defaults, and explicit guardrails so “convenient” does not become unrestricted shell access.
Stay in the agent chat (“is api running, and show the last fifty log lines”) instead of SSH-and-paste.
Features
Read-only by default (
DOKKU_MCP_MODE=read-only)Shared
asyncsshsession (not a new connection per tool call)Structured parsers for Dokku CLI output (prefer
--format jsonwhen available)App allowlist / denylist
Config secrets masked unless
reveal_secrets=TrueMutating tools require
read-writemode; restart / scale / set-config also needconfirm=TrueNo free-form
dokku_exec— one Dokku command, one tool, one parserdestroy_appis not included
Related MCP server: VPS Docker MCP (Advanced)
Install
# From source (development)
uv sync
# Run from this checkout without a global install
uv run dokku-mcpWhen published to PyPI: uvx dokku-mcp or pip install dokku-mcp.
Quick start
Confirm Dokku SSH works the forced-command way (this is what the server uses):
ssh dokku@your-host apps:listCopy
.env.exampleor set the same variables in your MCP clientenvblock.Add the server to Cursor or Claude Desktop (see below), reload MCP, and ask: “What apps are on my Dokku host?”
If the dokku server does not appear under MCP tools, check the MCP panel logs — bad host, key path, or a failed uv start show up there before any chat error.
Configuration
Variable | Default | Description |
| (required) | Dokku SSH hostname |
|
| SSH user (Dokku convention) |
| (agent/defaults) | Path to private key |
|
| SSH port |
|
|
|
| empty | Comma-separated apps; empty = all |
| empty | Comma-separated apps always blocked |
Dokku’s SSH user uses a forced command: this server sends plugin invocations such as apps:list, not dokku apps:list.
Tools
Read-only
Tool | Dokku command | Notes |
|
| Filtered by allow/deny lists |
|
| Process / running state |
|
| Secrets masked by default |
|
| Default 50 lines, hard max 500 |
|
| VHOST report |
| derived | HTTPS URLs from domains |
Mutating (gated)
Tool | Dokku command | Guards |
|
|
|
|
|
|
|
|
|
|
|
|
confirm must be passed explicitly on the tool call — it is never inferred from chatty assent.
Example prompts
You type | Tools |
“What apps are on my Dokku host?” |
|
“Is |
|
“Show the last 50 log lines for |
|
“Which env keys does |
|
MCP client setup
Cursor
Add to ~/.cursor/mcp.json or the project .cursor/mcp.json:
{
"mcpServers": {
"dokku": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/dokku-mcp-server",
"dokku-mcp"
],
"env": {
"DOKKU_HOST": "dokku.example.com",
"DOKKU_SSH_USER": "dokku",
"DOKKU_SSH_KEY_PATH": "/home/YOU/.ssh/id_ed25519",
"DOKKU_MCP_MODE": "read-only"
}
}
}
}Cursor / Claude Desktop
Same env block with:
"command": "uvx",
"args": ["dokku-mcp"]See examples/cursor_mcp.json and examples/claude_desktop_config.json.
Local entrypoints
uv run dokku-mcp
python -m dokku_mcp
fastmcp run dokku_mcp.server:mcpDevelopment
uv sync --all-extras
uv run pytest -m "not integration" -q
# Live smoke test against your Dokku box:
DOKKU_HOST=... DOKKU_SSH_KEY_PATH=... uv run pytest -m integration -qLayout: src/dokku_mcp/ — server.py, ssh.py, config.py, parsers.py, and tools/ (one module per Dokku concern).
Security notes
Prefer
read-onlyfor day-to-day LLM access.Use allowlists on shared hosts; denylist always wins.
Prefer an SSH agent or default
IdentityFileover embedding private key paths when you can.Treat
reveal_secrets=Trueandread-writeas elevated privileges.There is no open-ended shell tool; that is intentional.
Contributing
Issues and PRs welcome — especially fixture captures from real Dokku versions and extra read-only reports that fit the “one command, one tool, one parser” rule.
License
MIT — see LICENSE.
Available Tools
10 toolsapp_configApp ConfigA
Get environment config vars for a Dokku app.
Side effects: none (read-only).
Secret-looking keys (PASSWORD, TOKEN, DATABASE_URL, etc.) are masked as ***
unless reveal_secrets=True is passed explicitly.
Inputs: app (required), reveal_secrets. Returns: object
app_domainsApp DomainsA
Get domain / VHOST report for a Dokku app.
Side effects: none (read-only).
Runs domains:report <app>.
Inputs: app (required). Returns: object
app_logsApp LogsA
Fetch recent logs for a Dokku app.
Side effects: none (read-only). Default lines=50; hard maximum is 500.
Inputs: app (required), lines. Returns: result
app_reportApp ReportA
Get process report for a Dokku app (running state, scale, etc.).
Side effects: none (read-only).
Runs ps:report <app>.
Inputs: app (required). Returns: object
app_urlApp UrlB
Derive public URLs for a Dokku app from its domains.
Side effects: none (read-only). Convenience wrapper over domains:report; defaults to https:// scheme.
Inputs: app (required), scheme. Returns: object
create_appCreate AppA
Create a new Dokku app.
Side effects: creates an application on the Dokku host. Requires DOKKU_MCP_MODE=read-write. App names must be lowercase alphanumeric with optional hyphens.
Inputs: name (required). Returns: object
list_appsList AppsA
List Dokku apps on the host.
Side effects: none (read-only). Respects DOKKU_APP_ALLOWLIST / DOKKU_APP_DENYLIST — denied apps are filtered out.
Inputs: no named parameters. Returns: result
restart_appRestart AppA
Restart all processes for a Dokku app.
Side effects: restarts the application (downtime possible). Requires DOKKU_MCP_MODE=read-write and confirm=True.
Inputs: app (required), confirm. Returns: object
scale_appScale AppA
Scale process types for a Dokku app (e.g. web=2, worker=1).
Side effects: changes running process counts. Requires DOKKU_MCP_MODE=read-write and confirm=True.
Inputs: app (required), scale (required), confirm. Returns: object
set_configSet ConfigA
Set one or more config vars on a Dokku app.
Side effects: updates environment variables; restarts the app unless no_restart=True. Requires DOKKU_MCP_MODE=read-write and confirm=True. Values are never echoed back in the response — only keys are returned.
Inputs: app (required), pairs (required), confirm, no_restart. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools are clearly distinct: list_apps is the only app-level listing, app_report/app_config/app_logs/app_domains/app_url each target a different aspect of an app, and the write tools (create_app, set_config, restart_app, scale_app) have distinct actions. The only mild overlap is app_domains vs app_url, since app_url is a convenience wrapper over domains:report, but the descriptions make the relationship clear.
The naming pattern is mostly consistent: read operations use app_* (app_report, app_config, app_logs, app_domains, app_url) plus list_apps, and write operations use verb_app (create_app, set_config, restart_app, scale_app). The minor inconsistency is that list_apps breaks the app_* pattern and set_config/restart_app/scale_app use verb_app rather than app_verb, but the overall convention is still predictable.
10 tools is well-scoped for a Dokku MCP server. The read-only surface covers the most common inspection needs (list, report, config, logs, domains, URL), and the write surface covers the core app lifecycle operations (create, config, restart, scale). No tool feels redundant or unnecessary.
The tool surface covers the primary Dokku workflows: listing/creating apps, inspecting app state/config/logs/domains, updating config, restarting, and scaling. Obvious gaps include app deletion, app destruction, and process management (e.g. ps:scale is covered but ps:restart is not), but these are reasonable omissions for a safe MCP server and agents can work around them.
Maintenance
Related MCP Connectors
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Hosted remote MCP for protected account access, permissions, activity history and supported undo.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceSecurely inspect and operate self-hosted infrastructure including Linux host health, Docker containers and logs, Dokploy deployments, and OCI resources through a narrowly scoped, auditable MCP gateway.MIT
- FlicenseBqualityBmaintenanceEnables safe VPS diagnostics and Docker/Docker Compose management over SSH, providing predefined read-only and mutating tools for system monitoring, container inspection, and Compose orchestration without exposing arbitrary shell execution.26-
- AlicenseNot gradedqualityBmaintenanceEnables read-only inspection and confirmed mutation operations on a single VPS over SSH, including host health, Docker, Compose, Swarm, firewall, and system debugging tools.36 npm1MIT
- AlicenseBqualityCmaintenanceEnables MCP-compatible AI assistants to inspect and manage local or remote servers in plain language, covering system health, Docker containers, services, ports, disks, scoped files, and read-only database queries over key-only SSH. Write actions such as container restarts, file edits, and allowlisted dev commands require client approval.14MIT