<p align="center">
  <a href="https://www.npmjs.com/package/mcp-dokploy"><img alt="npm version" src="https://img.shields.io/npm/v/mcp-dokploy?color=14b8a6" /></a>
  <img src="assets/banner.svg" alt="Dokploy MCP — connect Codex to Dokploy and Cloudflare" width="100%" />
</p>

<p align="center">
  <a href="https://github.com/HaroldXd/Mcp_Dokploy/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/HaroldXd/Mcp_Dokploy/actions/workflows/ci.yml/badge.svg" /></a>
  <a href="https://github.com/HaroldXd/Mcp_Dokploy/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/HaroldXd/Mcp_Dokploy?color=14b8a6" /></a>
  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-60a5fa" /></a>
  <img alt="Node.js 22 or newer" src="https://img.shields.io/badge/Node.js-22%2B-84cc16" />
</p>

<p align="center">
  <strong>Your infrastructure. Your credentials. One conversation.</strong><br />
  Deploy applications and manage Cloudflare DNS from Codex or Claude with a local MCP server.
</p>

<p align="center">
  <a href="#quick-start">Quick start</a> ·
  <a href="https://github.com/HaroldXd/Mcp_Dokploy/releases/latest">Download</a> ·
  <a href="docs/README.es.md">Español</a> ·
  <a href="docs/CLAUDE.md">Claude setup</a> ·
  <a href="CONTRIBUTING.md">Contribute</a> ·
  <a href="docs/PUBLISHING.md">Distribution</a>
</p>

---

## What you can do

| Deploy your stack | Configure your apps | Connect your domains |
| --- | --- | --- |
| Create applications and Compose services | Patch environment variables | Manage A, AAAA and CNAME records |
| Start deployments and inspect results | Configure projects and environments | Preview DNS changes and detect conflicts |
| Inspect logs, databases and backups | Read server information through Dokploy | Configure Dokploy domains and HTTPS |

**9 MCP tools · 232 catalogued Dokploy operations · Local execution · MIT licensed**

The bundled skill discovers the exact API schema as needed, instead of exposing hundreds of individual tools. Operations depend on the API supported by your installed Dokploy version.

## Quick start

You need **Node.js 22+** and your preferred client: **Codex**, **Claude Code**, or **Claude Desktop**. Codex and Claude Code plugin installation requires their respective CLI. The MCP runs on your computer and does not require a separate model-provider API key.

### One command with npm

> npm publication is being prepared. Until the first npm version is available, use the ZIP or source installation below.

```sh
# Codex
npx -y mcp-dokploy@latest install codex

# Claude Code ("claude" is also accepted)
npx -y mcp-dokploy@latest install claude-code

# Claude Desktop
npx -y mcp-dokploy@latest install claude-desktop
```

Choose **one** command for your client. The installer downloads the runtime to a permanent user directory, registers the connector and prints where to configure your credentials. You do not need to clone the repository or build TypeScript. npm installs use the `mcp-dokploy` marketplace; ZIP/source installations use `dokploy-tools`.

The name on npm is **[mcp-dokploy](https://www.npmjs.com/package/mcp-dokploy)**. To update, rerun the same command with `@latest` and restart your client. If you previously installed the ZIP/source plugin, uninstall `dokploy-cloudflare@dokploy-tools` in that client before switching to npm to avoid duplicate tools. Your credentials file is shared and preserved.

### Option 1 — Download the plugin

1. Download the ZIP from the [latest release](https://github.com/HaroldXd/Mcp_Dokploy/releases/latest).
2. Extract it into a permanent folder and open a terminal there.
3. Run:

```sh
node install.mjs
```

Choose another client with an installer flag:

| Client | Command from the extracted ZIP |
| --- | --- |
| Codex | `node install.mjs` |
| Claude Code | `node install.mjs --client claude-code` |
| Claude Desktop | `node install.mjs --client claude-desktop` |

Claude Code receives the MCP and skill. Claude Desktop receives the MCP and a `dokploy_workflow` prompt. Its existing configuration is preserved and backed up. See the [Claude guide](docs/CLAUDE.md).

### Option 2 — Install from source

```sh
git clone https://github.com/HaroldXd/Mcp_Dokploy.git
cd Mcp_Dokploy
npm ci
npm run setup
```

For Claude, replace the last command with `npm run setup:claude-code` or `npm run setup:claude-desktop`.

The Codex and Claude Code installers register the local `dokploy-tools` marketplace and install the MCP with the `dokploy-control` skill. Desktop writes one MCP entry using absolute paths. Avoid installing duplicate server entries in the same client.

### Add your credentials

Edit the configuration file printed by the installer:

| System | Configuration path |
| --- | --- |
| Windows | `%USERPROFILE%\.config\dokploy-mcp\config.env` |
| macOS / Linux | `~/.config/dokploy-mcp/config.env` |

```dotenv
DOKPLOY_URL=https://dokploy.example.com
DOKPLOY_API_KEY=
CLOUDFLARE_API_TOKEN=
CLOUDFLARE_ZONE_IDS=
DOKPLOY_READ_ONLY=false
```

- **Dokploy:** generate a token under **Settings → Profile → API/CLI**. Use the panel URL, without `/api`.
- **Cloudflare:** use an API Token with **DNS Edit** and **Zone Read**, restricted to the zones you want to manage. Cloudflare is optional for Dokploy operations.
- **Zone IDs:** optional comma-separated allowlist. Without it, accessible zones are determined by your Cloudflare token.

Keep credentials on your own computer. They are not included in the repository or release. The configuration is a local plaintext file: protect it with your user permissions. Environment variables override the file; `DOKPLOY_MCP_CONFIG` selects a different path.

**Restart your client after installation or credential changes.** In Claude Desktop, fully quit and reopen the application.

## Try a conversation

```text
Use dokploy-control to list my projects and applications.
```

```text
Deploy this repository to staging and inspect the deployment result.
```

```text
Connect app.example.com to this application with Cloudflare DNS and HTTPS.
```

```text
Preview these environment variable changes while preserving the other keys.
```

Start with read-only discovery. Set `DOKPLOY_READ_ONLY=true` to block writes through both API clients.

## How it connects

```mermaid
flowchart LR
    A[Codex or Claude] -->|Local stdio| B[Dokploy MCP]
    B -->|API key · HTTPS| C[Dokploy]
    B -->|Scoped API Token · HTTPS| D[Cloudflare DNS]
    C --> E[Applications · Compose · Databases]
    D --> F[A · AAAA · CNAME]
```

## Tools at a glance

| Tool | Purpose |
| --- | --- |
| `connection_status` | Check local configuration without printing credentials |
| `dokploy_catalog` | Discover endpoints, methods and exact input schemas |
| `dokploy_call` | Call a validated endpoint; supports dry runs |
| `application_env_patch` | Preview and apply variable patches with a revision check |
| `cloudflare_zones` | List permitted zones with pagination |
| `cloudflare_records` | Inspect DNS records before a change |
| `cloudflare_upsert` | Preview or apply A/AAAA/CNAME changes |
| `cloudflare_delete` | Delete an explicitly selected record with confirmation |
| `dns_check` | Resolve records through the system resolver |

## Verification and current limits

Fifteen automated tests cover API validation, mocked HTTP requests, variable preservation, redaction, DNS conflicts, Claude Desktop configuration merging, npm catalogs, CLI dispatch, the workflow prompt and a real MCP stdio handshake. Codex and Claude Code manifests are packaged separately for their hosts. Read-only authentication to Dokploy and Cloudflare has been checked against a configured instance; production deployments and restores have not been certified.

<details>
<summary><strong>Read before authorizing infrastructure changes</strong></summary>

- The API catalog is a versioned snapshot. A dry run validates parameters, not compatibility with your server.
- Multi-step workflows are guided by the skill. There is no distributed transaction, automatic rollback or durable operation journal.
- Environment patches preserve other keys and build settings, but use an optimistic revision check rather than an atomic lock. Complex multiline documents are refused.
- VPS operations use Dokploy APIs. This plugin does not provide SSH or an arbitrary host shell.
- DNS supports existing Cloudflare zones and A/AAAA/CNAME records. It does not buy domains, change nameservers, modify MX/TXT or change zone-wide SSL settings.
- Local DNS resolution does not establish global propagation or HTTPS health. Verify those separately.
- Known secret fields and configured tokens are redacted. Application logs may contain other sensitive data.
- Dokploy authorization follows the supplied token; there is no additional project allowlist. Destructive confirmation parameters guard against mistakes and do not replace user authorization.
- Mutations are not automatically retried. Inspect current state after a timeout before trying again.
- HTTPS is required. `DOKPLOY_ALLOW_HTTP=true` is only for trusted tunnels or networks; TLS validation is never disabled.

</details>

## Development

```sh
npm ci
npm test
npm run package:plugin
npm run doctor
```

`doctor` checks local configuration presence; it does not validate credentials. Ask Codex to list projects and zones to check read access.

```text
src/        MCP server, API clients and validation
schemas/    Dokploy OpenAPI snapshot and upstream license
skills/     Codex operating procedures
scripts/    Installers, packaging and smoke checks
tests/      API behavior and MCP protocol tests
docs/       Spanish guide, roadmap and publishing instructions
```

The generated bundle lives in `plugins/dokploy-cloudflare/` and includes JavaScript dependencies. Node.js must be installed on the destination computer.

## Community and license

Contributions are welcome — read [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities through [SECURITY.md](SECURITY.md). The project is available under the [MIT License](LICENSE); bundled dependencies retain their own licenses.

This is an independent community integration, not an official product of Dokploy, Cloudflare or OpenAI. GitHub distribution is separate from acceptance into the official plugin directory; see [publishing](docs/PUBLISHING.md).

Built on the official [Dokploy API](https://docs.dokploy.com/docs/api), [Dokploy OpenAPI specification](https://github.com/Dokploy/sdk), [Cloudflare API](https://developers.cloudflare.com/fundamentals/api/get-started/) and [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk).