{"id":28509276,"url":"https://github.com/dokploy/mcp","last_synced_at":"2026-01-20T17:54:57.935Z","repository":{"id":296928146,"uuid":"994587566","full_name":"Dokploy/mcp","owner":"Dokploy","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-13T23:26:16.000Z","size":56,"stargazers_count":21,"open_issues_count":2,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-25T08:51:06.935Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dokploy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-02T07:05:26.000Z","updated_at":"2025-07-23T20:46:06.000Z","dependencies_parsed_at":"2025-06-03T12:04:03.961Z","dependency_job_id":"6eb9c668-75fd-4045-9472-381f3dbd8daf","html_url":"https://github.com/Dokploy/mcp","commit_stats":null,"previous_names":["dokploy/mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Dokploy/mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dokploy%2Fmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dokploy%2Fmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dokploy%2Fmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dokploy%2Fmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dokploy","download_url":"https://codeload.github.com/Dokploy/mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dokploy%2Fmcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268215611,"owners_count":24214365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-08T22:08:04.514Z","updated_at":"2026-01-20T17:54:57.884Z","avatar_url":"https://github.com/Dokploy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dokploy MCP Server\n\n[![npm version](https://img.shields.io/npm/v/@ahdev/dokploy-mcp.svg)](https://www.npmjs.com/package/@ahdev/dokploy-mcp) [\u003cimg alt=\"Install in VS Code (npx)\" src=\"https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square\u0026label=Install%20Dokploy%20MCP\u0026color=0098FF\"\u003e](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22dokploy-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ahdev%2Fdokploy-mcp%40latest%22%5D%7D)\n\nDokploy MCP Server exposes Dokploy functionalities as tools consumable via the Model Context Protocol (MCP). It allows MCP-compatible clients (e.g., AI models, other applications) to interact with your Dokploy server programmatically.\n\nThis server focuses exclusively on **tools** for direct Dokploy API operations, providing a clean and efficient interface for project and application management.\n\n## 🛠️ Getting Started\n\n### Requirements\n\n- Node.js \u003e= v18.0.0 (or Docker)\n- Cursor, VS Code, Claude Desktop, or another MCP Client\n- A running Dokploy server instance\n\n### Install in Cursor\n\nGo to: `Settings` -\u003e `Cursor Settings` -\u003e `MCP` -\u003e `Add new global MCP server`\n\nAdd this to your Cursor `~/.cursor/mcp.json` file. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahdev/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternative: Use Bun\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"@ahdev/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternative: Use Deno\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"deno\",\n      \"args\": [\"run\", \"--allow-env\", \"--allow-net\", \"npm:@ahdev/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### Install in Windsurf\n\nAdd this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info.\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahdev/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Install in VS Code\n\n[\u003cimg alt=\"Install in VS Code (npx)\" src=\"https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square\u0026label=Install%20Dokploy%20MCP\u0026color=0098FF\"\u003e](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22dokploy-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ahdev%2Fdokploy-mcp%40latest%22%5D%7D)\n[\u003cimg alt=\"Install in VS Code Insiders (npx)\" src=\"https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square\u0026label=Install%20Dokploy%20MCP\u0026color=24bfa5\"\u003e](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22dokploy-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ahdev%2Fdokploy-mcp%40latest%22%5D%7D)\n\nAdd this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.\n\n```json\n{\n  \"servers\": {\n    \"dokploy-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahdev/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Install in Zed\n\nAdd this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info.\n\n```json\n{\n  \"context_servers\": {\n    \"dokploy-mcp\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@ahdev/dokploy-mcp\"]\n      },\n      \"settings\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Install in Claude Desktop\n\nAdd this to your Claude Desktop `claude_desktop_config.json` file. See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info.\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahdev/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Install in BoltAI\n\nOpen the \"Settings\" page of the app, navigate to \"Plugins,\" and enter the following JSON:\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahdev/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Using Docker\n\nThe Docker container supports both **stdio** and **HTTP** transport modes, making it flexible for different deployment scenarios.\n\n1.  **Build the Docker Image:**\n\n    ```bash\n    git clone https://github.com/Dokploy/mcp.git\n    cd dokploy-mcp\n    docker build -t dokploy-mcp .\n    ```\n\n2.  **Manual Docker Commands:**\n\n    **Stdio Mode (for MCP clients):**\n\n    ```bash\n    docker run -it --rm \\\n      -e DOKPLOY_URL=https://your-dokploy-server.com/api \\\n      -e DOKPLOY_API_KEY=your_token_here \\\n      dokploy-mcp\n    ```\n\n    **HTTP Mode (for web applications):**\n\n    ```bash\n    docker run -it --rm \\\n      -p 8080:3000 \\\n      -e MCP_TRANSPORT=http \\\n      -e DOKPLOY_URL=https://your-dokploy-server.com/api \\\n      -e DOKPLOY_API_KEY=your_token_here \\\n      dokploy-mcp\n    ```\n\n3.  **Docker Compose:**\n\n    Use the provided `docker-compose.yml` for production deployments:\n\n    ```bash\n    # Start HTTP service\n    docker-compose up -d dokploy-mcp-http\n\n    # View logs\n    docker-compose logs -f dokploy-mcp-http\n    ```\n\n4.  **MCP Client Configuration:**\n\n    **For stdio mode (Claude Desktop, VS Code, etc.):**\n\n    ```json\n    {\n      \"mcpServers\": {\n        \"dokploy-mcp\": {\n          \"command\": \"docker\",\n          \"args\": [\n            \"run\",\n            \"-i\",\n            \"--rm\",\n            \"-e\",\n            \"DOKPLOY_URL=https://your-dokploy-server.com/api\",\n            \"-e\",\n            \"DOKPLOY_API_KEY=your_token_here\",\n            \"dokploy-mcp\"\n          ]\n        }\n      }\n    }\n    ```\n\n    **For HTTP mode (web applications):**\n\n    Start the HTTP server first, then configure your client to connect to `http://localhost:3000/mcp`.\n\n### Install in Windows\n\nThe configuration on Windows is slightly different compared to Linux or macOS. Use `cmd` as the command wrapper:\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"-y\", \"@ahdev/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Environment Variables\n\n- `DOKPLOY_URL`: Your Dokploy server API URL (required)\n- `DOKPLOY_API_KEY`: Your Dokploy API authentication token (required)\n\n## 🚀 Transport Modes\n\nThis MCP server supports multiple transport modes to suit different use cases:\n\n### Stdio Mode (Default)\n\nThe default mode uses stdio for direct process communication, ideal for desktop applications and command-line usage.\n\n```bash\n# Run with stdio (default)\nnpx -y @ahdev/dokploy-mcp\n# or\nnpm run start:stdio\n```\n\n### HTTP Mode (Streamable HTTP + Legacy SSE)\n\nModern HTTP mode exposes the server via HTTP/HTTPS supporting **both modern and legacy protocols** for maximum compatibility:\n\n- **Streamable HTTP (MCP 2025-03-26)** - Modern protocol with session management\n- **Legacy SSE (MCP 2024-11-05)** - Backwards compatibility for older clients\n\n```bash\n# Run with HTTP mode\nnpm run start:http\n# or\nnpx -y @ahdev/dokploy-mcp --http\n# or via environment variable\nMCP_TRANSPORT=http npx -y @ahdev/dokploy-mcp\n```\n\n**Modern Streamable HTTP Endpoints:**\n\n- **POST /mcp** - Client-to-server requests\n- **GET /mcp** - Server-to-client notifications\n- **DELETE /mcp** - Session termination\n- **GET /health** - Health check endpoint\n\n**Legacy SSE Endpoints (Backwards Compatibility):**\n\n- **GET /sse** - SSE stream initialization\n- **POST /messages** - Client message posting\n\n**Configuration:**\n\n- Internal port: `3000` (fixed)\n- External port: configurable via `EXTERNAL_PORT` (default: `3000`)\n- Supports both modern Streamable HTTP (MCP 2025-03-26) and legacy SSE (MCP 2024-11-05)\n- Session management with automatic cleanup for both transport types\n\n**Client Compatibility:**\n\nModern clients automatically use the Streamable HTTP endpoints, while legacy clients can connect using the SSE endpoints. The server handles both protocols simultaneously, ensuring compatibility with:\n\n- **Modern MCP clients** (Claude Desktop, Cline, etc.) → Use `/mcp` endpoints\n- **Legacy MCP clients** → Use `/sse` and `/messages` endpoints\n- **Custom integrations** → Choose the appropriate protocol for your needs\n\nFor detailed transport mode documentation and client examples, refer to the configuration examples above.\n\n## 📚 Available Tools\n\nThis MCP server provides **67 tools** organized into five main categories:\n\n### 🗂️ Project Management (6 tools)\n\n- `project-all` - List all projects\n- `project-one` - Get project by ID\n- `project-create` - Create new project\n- `project-update` - Update project configuration\n- `project-duplicate` - Duplicate project with optional service selection\n- `project-remove` - Delete project\n\n### 🚀 Application Management (26 tools)\n\n**Core Operations:**\n- `application-one`, `application-create`, `application-update`, `application-delete`\n- `application-deploy`, `application-redeploy`, `application-start`, `application-stop`, `application-reload`\n- `application-move`, `application-markRunning`, `application-cancelDeployment`\n\n**Git Providers:**\n- `application-saveGithubProvider`, `application-saveGitlabProvider`, `application-saveBitbucketProvider`\n- `application-saveGiteaProvider`, `application-saveGitProvider`, `application-disconnectGitProvider`\n\n**Configuration:**\n- `application-saveBuildType`, `application-saveEnvironment`, `application-saveDockerProvider`\n- `application-readAppMonitoring`, `application-readTraefikConfig`, `application-updateTraefikConfig`\n- `application-refreshToken`, `application-cleanQueues`\n\n### 🌐 Domain Management (9 tools)\n\n- `domain-byApplicationId` - List domains by application ID\n- `domain-byComposeId` - List domains by compose service ID\n- `domain-one` - Get domain by ID\n- `domain-create` - Create domain (application/compose/preview)\n- `domain-update` - Update domain configuration\n- `domain-delete` - Delete domain\n- `domain-validateDomain` - Validate domain DNS/target\n- `domain-generateDomain` - Suggest a domain for an app\n- `domain-canGenerateTraefikMeDomains` - Check Traefik.me availability on a server\n\n### 🐘 PostgreSQL Database Management (13 tools)\n\n**Core Operations:**\n- `postgres-create`, `postgres-one`, `postgres-update`, `postgres-remove`, `postgres-move`\n- `postgres-deploy`, `postgres-start`, `postgres-stop`, `postgres-reload`, `postgres-rebuild`\n\n**Configuration:**\n- `postgres-changeStatus`, `postgres-saveExternalPort`, `postgres-saveEnvironment`\n\n### 🐬 MySQL Database Management (13 tools)\n\n**Core Operations:**\n- `mysql-create`, `mysql-one`, `mysql-update`, `mysql-remove`, `mysql-move`\n- `mysql-deploy`, `mysql-start`, `mysql-stop`, `mysql-reload`, `mysql-rebuild`\n\n**Configuration:**\n- `mysql-changeStatus`, `mysql-saveExternalPort`, `mysql-saveEnvironment`\n\n**Tool Annotations:**\nAll tools include semantic annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) to help MCP clients understand their behavior and safety characteristics.\n\nFor detailed schemas, parameters, and usage examples, see **[TOOLS.md](TOOLS.md)**.\n\n## 🏗️ Architecture\n\nBuilt with **@modelcontextprotocol/sdk**, **TypeScript**, and **Zod** for type-safe schema validation:\n\n- **67 Tools** covering projects, applications, domains, PostgreSQL, and MySQL management\n- **Multiple Transports**: Stdio (default) and HTTP (Streamable HTTP + legacy SSE)\n- **Multiple Git Providers**: GitHub, GitLab, Bitbucket, Gitea, custom Git\n- **Robust Error Handling**: Centralized API client with retry logic\n- **Type Safety**: Full TypeScript support with Zod schema validation\n- **Tool Annotations**: Semantic hints for MCP client behavior understanding\n\n## 🔧 Development\n\nClone the project and install dependencies:\n\n```bash\ngit clone https://github.com/Dokploy/mcp.git\ncd dokploy-mcp\nnpm install\n```\n\nBuild:\n\n```bash\nnpm run build\n```\n\n### Local Configuration Example\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"/path/to/dokploy-mcp/src/index.ts\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Testing with MCP Inspector\n\n```bash\nnpx -y @modelcontextprotocol/inspector npx @ahdev/dokploy-mcp\n```\n\n### Documentation\n\n- **[TOOLS.md](TOOLS.md)** - Complete tool reference with schemas and examples\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contributing guidelines\n\n## 🔧 Troubleshooting\n\n### MCP Client Errors\n\n1. Try adding `@latest` to the package name.\n\n2. Make sure you are using Node v18 or higher to have native fetch support with `npx`.\n\n3. Verify your `DOKPLOY_URL` and `DOKPLOY_API_KEY` environment variables are correctly set.\n\n## 🤝 Contributing\n\nWe welcome contributions! If you'd like to contribute to the Dokploy MCP Server, please check out our [Contributing Guide](CONTRIBUTING.md).\n\n## 🆘 Support\n\nIf you encounter any issues, have questions, or want to suggest a feature, please [open an issue](https://github.com/Dokploy/mcp/issues) in our GitHub repository.\n\n## 📄 License\n\nThis project is licensed under the [Apache License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokploy%2Fmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdokploy%2Fmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokploy%2Fmcp/lists"}