better-caprover-mcp
Provides an MCP server for operating a CapRover server, exposing CapRover API operations to agents with configurable access modes, a default readonly mode, and planned confirmation for destructive calls.
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., "@better-caprover-mcp list my CapRover apps and their current status"
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.
Giving an agent the keys to a server is the hard part. A CapRover password is full access, and a model that can call "delete app" will sooner or later call it when it should not.
better-caprover-mcp gives the agent all possible CapRover actions over its API and puts the safety in code, not in a prompt. The server starts in readonly mode and a mode only goes up when you restart it with another setting. Every change can be previewed with dry_run. Deleting does nothing until the person has seen what would be lost and said yes, and the password and the values of your environment variables never come back in a reply.
The mode is the barrier, not the model's good manners. In
readonlythe write tools are not even registered, and every call is checked again when it runs.
What you get
Safe by default
Starts readonly. operate lets the agent change apps, admin also lets it delete. Only you can raise the mode.
Preview before it writes
Every change takes dry_run and returns what would change, without a write call to CapRover.
Confirmation before a delete
delete_app returns a preview and a one-time token tied to that exact call. It runs only when the call comes back with the token and the person's yes.
No secrets in the replies
Env var values are never returned (only isSet). The password and the values of an app's variables are masked in logs and errors.
Related MCP server: easypanel-mcp-server
Quick start
You need the address of your CapRover (https://captain.your-domain.com) and its password. CapRover has no user name, and servers with two-factor login turned on are not supported (ADR 0010).
1. Coding Agent
Add this to the MCP servers of your client (any AI that speaks MCP, such as Claude Code, Cursor, Codex, and others):
{
"mcpServers": {
"caprover": {
"command": "npx",
"args": ["-y", "better-caprover-mcp"],
"env": {
"CAPROVER_URL": "https://captain.your-domain.com",
"CAPROVER_PASSWORD": "your CapRover password",
"CAPROVER_MCP_MODE": "readonly"
}
}
}
}2. Providing on your own server to any AI
Run the server over HTTP on a machine you control, and point any MCP client at it. Bind to localhost only (127.0.0.1:3100), and put TLS in front for anything else.
docker run -d --name caprover-mcp -p 127.0.0.1:3100:3100 \
-e CAPROVER_URL=https://captain.your-domain.com \
-e CAPROVER_PASSWORD='your CapRover password' \
-e CAPROVER_MCP_MODE=readonly \
-e CAPROVER_MCP_TRANSPORT=http \
-e CAPROVER_MCP_HTTP_HOST=0.0.0.0 \
-e CAPROVER_MCP_HTTP_TOKEN='your-long-random-secret' \
-e CAPROVER_MCP_LOG_LEVEL=info \
-e CAPROVER_MCP_SURFACE=tools \
ghcr.io/guilhermebkel/better-caprover-mcp:latestThen point the client at it:
{
"mcpServers": {
"caprover": {
"url": "http://127.0.0.1:3100/mcp",
"headers": {
"Authorization": "Bearer your-long-random-secret"
}
}
}
}More on HTTP bind and TLS: docs/product/remote-http.md. Limits and other variables: Configuration.
Check the login
CAPROVER_URL=https://captain.your-domain.com CAPROVER_PASSWORD=... npx -y better-caprover-mcp initinit tests the login and prints the client configuration. Without the two variables it only prints the configuration.
Ask
Which of my apps run an image tagged latest?
Set LOG_LEVEL=debug on the api app, but show me what changes first.To let the agent change apps, set CAPROVER_MCP_MODE=operate; for deleting, admin.
Example
Real output of the built server against a CapRover 1.15.5. The agent asks to delete an app; nothing is deleted yet.
> delete_app {"app_name":"e2e-app"}
Not run. Would delete the app e2e-app (1 instances, image caprover/caprover-placeholder-app:latest,
0 custom domains) and 0 volumes. This cannot be undone. Show this to the person. Only if they say yes,
call delete_app again with the same inputs, user_confirmed true and this confirmation_token.
{"requires_confirmation":true,"confirmation_token":"718ebc698036ae0622c1246c60a46e0c","appName":"e2e-app",...}
> delete_app {"app_name":"e2e-app","user_confirmed":true,"confirmation_token":"718ebc698036ae0622c1246c60a46e0c"}
Deleted the app e2e-app and 0 volumes.A token that was used, expired (5 minutes) or made for another call is refused, and the reply carries a new preview.
Access modes
The mode decides which operations the client sees at all. Only the person can change it, by restarting the server with another CAPROVER_MCP_MODE.
Mode | Operations available |
| All possible CapRover actions that only read |
| Read, plus all possible actions that change something and can be changed back |
| Read, change, plus all possible actions that delete ( |
| All of the above, plus all the critical ones |
CAPROVER_MCP_TOOLSETS then picks which groups of operations are registered. The default is core,apps,domains,oneclick; the other toolsets are opt-in so the tool list stays short. Ask get_access what is on and why a call was denied.
Operations
The server exposes 71 operations in ten toolsets. The tier and toolset of every one, and the SDK method behind it, are in docs/product/risk-tiers.md. A changing call takes dry_run; a deleting or critical call returns a preview and a confirmation_token first, and asks the person through the client when the client supports it.
Toolset | Operations |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Some SDK methods are kept for later, each with its reason in scripts/sdk-coverage.json: updateConfigAndSave (the code surface), setProConfigs, getGoAccessReport and createBackup. get_app_runtime and list_apps_runtime need a CapRover version that has the runtime endpoint (1.15.5 has none).
Configuration
Variable | Default | Meaning |
| none | The address of your CapRover, with |
| none | The CapRover password |
|
|
|
| off | Set to |
|
| How the operations are exposed: |
|
| Comma-separated toolsets to register: |
|
|
|
|
|
|
| none | Bearer secret for |
|
| Address for |
|
| Port for |
|
| Max POST body size on |
|
| Max MCP HTTP requests per minute, counted in two buckets: failed auth and authenticated traffic. Each bucket is shared by every caller. |
|
| Max concurrent Streamable HTTP MCP sessions |
|
| Idle lifetime of an HTTP MCP session (ms); each request renews it |
|
| Max parallel tool runs in this MCP instance |
Without CAPROVER_URL and CAPROVER_PASSWORD the server still starts, and every call tells the model what is missing.
How it works
agent ──▶ 1. MODE ──▶ 2. VALIDATE ──▶ 3. PREVIEW / CONFIRM ──▶ 4. CALL ──▶ 5. REDACT
(MCP) is the tool strict schema, dry_run, or a token CapRover mask password
registered? errors list for a delete API (SDK) and env values
valid valuesThe work is split on purpose:
Part | Does | Why |
Operations ( | One class per thing a person does, with its schema, risk tier and description | One manifest feeds every surface and the policy |
Policy and runner ( | Applies the mode, | Rules that cannot fail live in code with a test, never only in a prompt |
Entry points ( | Start the program: arguments, transport, | They only call the builders; no operation, policy or adapter logic |
CapRover adapter ( | The only place that imports the official | The SDK is experimental; one folder absorbs its changes |
Decisions are in docs/adr/, the rules operations follow in docs/mcp-standards.md.
Privacy and safety
The only network exit is your
CAPROVER_URL. No telemetry, no analytics, nothing else is contacted.The server never runs a command on your machine and does not read your files. It only reads its environment variables.
Secrets stay out. The password and env var values are masked in every reply, log and error, and tested with fake secrets.
The CapRover password is full access. The modes are enforced by this server, not by CapRover, so give it to a client you trust.
Found a way around any of this? Open an issue without secrets in it.
How it compares
The CapRover dashboard and CLI are the reference for doing it by hand. This server lets an agent do the same steps, with a preview and a confirmation you control.
A generic MCP wrapper over the HTTP API typically gives the agent every endpoint with no modes and no confirmation. Here there is no "send any request" tool: that SDK method is left out on purpose (ADR 0003).
Other CapRover MCP servers exist. This one is a separate, unrelated project, with a one-command setup and the safety rules above.
FAQ
No. The code lasts 30 seconds. Over stdio, a client restarts the server each session; over HTTP the process is long-lived, but the server still has no way to obtain a fresh code, so it cannot be kept in an environment variable. The server logs in with the password only (ADR 0010).
No. The mode is read at startup from the environment, and nothing the agent can call changes it. Tell it to ask you, and restart the server with CAPROVER_MCP_MODE=operate or admin.
The endpoint it uses is missing in older CapRover versions (1.15.5 has none). The reply says so and points to get_app_logs and get_build_logs.
Roadmap
Core: the first operations on the
toolssurface, access modes,dry_run, confirmation token, redaction, tested against a real CapRover.The rest of the CapRover API: #3 — all possible CapRover actions in toolsets; some SDK methods stay planned, with reasons.
Diagnostics (
diagnose_app,find_issues,redeploy_app,bulk_env_update): #4Code Mode (
searchandexecutein a sandbox) and a benchmark: #5 — thecodesurface and the sandbox are built (CAPROVER_MCP_SURFACE); the benchmark that picks the default is still to runRemote HTTP (one CapRover server per MCP instance): #6 — multi-server in one process is out of scope; run one instance per Captain.
Contributing
Issues and pull requests are welcome. Start with AGENTS.md, which says what to read for each kind of task; vocabulary is in GLOSSARY.md and design decisions in docs/adr/.
Development
Needs the Node version in .nvmrc and pnpm.
nvm use
pnpm install
pnpm check # typecheck, lint, dead code, duplication, SDK drift, tests, build and a smoke run of the bundlepnpm test:integration runs the tests that need a real CapRover (CI starts one; locally, scripts/start-caprover.sh starts a throwaway CapRover in Docker with its default password and waits until it is ready; or set CAPROVER_TEST_URL and CAPROVER_TEST_PASSWORD to use your own), and needs pnpm build first. A second run reuses the CapRover that is installed, so it is fast. To remove it: docker swarm leave --force and docker rm -f captain-install. pnpm sdk:drift fails when the CapRover SDK has a method that is not classified in scripts/sdk-coverage.json.
pnpm smoke -- docker run -i --rm <image> runs the same smoke test against an image. Read AGENTS.md first: it says what to read for each kind of task.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Maintenance
Related MCP Connectors
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceProduction-grade MCP server that gives AI agents safe access to your local dev environment: filesystem, databases, processes, and OpenAPI specs.1540 npm4MIT
- AlicenseBqualityCmaintenanceMCP Server for full Easypanel control via Claude Code, Cursor, and Claude Desktop. Provides 37 tools for deploy, logs, env vars, domains, databases, and monitoring with built-in safety guards.5765 npm4MIT
- AlicenseAqualityDmaintenanceMCP server that wraps Docker, Caddy, and GitHub Actions operations on a remote VPS, enabling Claude to take read-then-write-with-confirmation infrastructure actions over SSH with a service allowlist and audit-trail-friendly responses.8MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents full access to the Clever Cloud API through three tools: search, execute, and doc, using a code mode pattern to compose API commands.4Apache 2.0