Skip to main content
This guide will help you set up the Dokploy MCP Server for local development, testing, and contributions.

​
Prerequisites

Node.js v18.0.0 or higher is required for native fetch support.
Ensure you have the following installed:
  • Node.js >= v18.0.0
  • npm (comes with Node.js)
  • Git
  • A running Dokploy server instance for testing

​
Clone and Install

  1. Fork and clone the repository:
git clone https://github.com/Dokploy/mcp.git
cd dokploy-mcp
  1. Set upstream remote (for contributors):
git remote add upstream https://github.com/Dokploy/mcp.git
  1. Install dependencies:
npm install
This will install all production and development dependencies including:
  • @modelcontextprotocol/sdk - MCP protocol implementation
  • axios - HTTP client for Dokploy API
  • zod - Schema validation
  • express - HTTP server (for HTTP mode)
  • TypeScript and ESLint tooling

​
Available Scripts

The package.json defines several useful scripts:

​
Build Commands

# Full build: clean, compile TypeScript, and set permissions
npm run build

# Watch mode: recompile on file changes
npm run dev

# Clean build artifacts
npm run clean

​
Run Commands

# Start in stdio mode (default)
npm run start:stdio

# Start in HTTP mode
npm run start:http

# Start in legacy SSE mode
npm run start:sse

# Build and start HTTP mode
npm run dev:http

​
Code Quality

# Lint TypeScript files
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code with Prettier
npm run format

# Check formatting without changes
npm run format:check

# Type check without compilation
npm run type-check

# Run all pre-commit checks
npm run precommit

​
Development Workflow

​
1. Set Up Environment Variables

Create a local configuration for testing. You’ll need:
  • DOKPLOY_URL: Your Dokploy server API URL (e.g., https://your-dokploy-server.com/api)
  • DOKPLOY_API_KEY: Your Dokploy API authentication token

​
2. Build the Project

npm run build
This compiles TypeScript to JavaScript in the build/ directory.

​
3. Test Locally with MCP Inspector

The MCP Inspector is the recommended way to test your changes: 
npx -y @modelcontextprotocol/inspector npx @ahdev/dokploy-mcp
Or test your local build directly: 
DOKPLOY_URL=https://your-server.com/api \
DOKPLOY_API_KEY=your_token \
npx @modelcontextprotocol/inspector node build/index.js
The Inspector provides:
  • Interactive tool testing
  • Request/response inspection
  • Schema validation
  • Real-time debugging

​
4. Test with Your MCP Client

Configure your MCP client to use your local build: 
{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/dokploy-mcp/src/index.ts"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}
Replace /path/to/dokploy-mcp with the actual path to your cloned repository.

​
5. Make Changes

The development cycle:
  1. Make code changes in src/
  2. Run npm run build to compile
  3. Test with MCP Inspector or your MCP client
  4. Run npm run precommit to verify code quality
  5. Repeat as needed
Use npm run dev to watch for changes and automatically recompile TypeScript during development.

​
Code Structure Overview

Understanding the codebase structure: 
src/
├── index.ts              # Entry point, handles stdio/HTTP mode selection
├── server.ts             # MCP server initialization
├── http-server.ts        # HTTP/SSE transport implementation
├── mcp/
│   └── tools/            # All 67 MCP tools organized by category
│       ├── application/  # Application management tools
│       ├── domain/       # Domain management tools
│       ├── mysql/        # MySQL database tools
│       ├── postgres/     # PostgreSQL database tools
│       └── project/      # Project management tools
├── types/                # TypeScript type definitions
└── utils/                # Utility functions and helpers
    └── logger.js         # Logging utilities

​
Key Files

  • src/index.ts:42 - Main entry point that determines transport mode (stdio or HTTP)
  • src/server.ts - Creates and configures the MCP server instance
  • src/http-server.ts - Express-based HTTP server for web deployments
  • src/mcp/tools/ - Tool implementations using Zod schemas for validation

​
Adding a New Tool

When adding new Dokploy tools:
  1. Create a new file in the appropriate src/mcp/tools/ subdirectory
  2. Define the tool schema using Zod
  3. Implement the handler function
  4. Add semantic annotations (readOnlyHint, destructiveHint, idempotentHint)
  5. Register the tool in the server configuration
  6. Update documentation in TOOLS.md

​
Testing Strategies

​
Manual Testing

  1. Unit testing: Test individual tool functions
  2. Integration testing: Test with MCP Inspector
  3. End-to-end testing: Test with real MCP clients (Claude Desktop, VS Code)

​
Test Both Transport Modes

Always test changes in both modes: 
# Test stdio mode
node build/index.js

# Test HTTP mode
node build/index.js --http
# Then visit http://localhost:3000/health

​
Debugging Tips

​
Enable Verbose Logging

The codebase uses a custom logger (see src/utils/logger.js). Logs go to stderr to avoid interfering with stdio transport.

​
Common Issues

Run npm run type-check to see detailed type errors without generating build artifacts.
Run npm run lint:fix to automatically fix common linting issues.
Check that you’re not logging to stdout - use the logger utility which writes to stderr.
Ensure port 3000 is available or set a different port via code changes.

​
Inspect Tool Schemas

Use the MCP Inspector to validate your tool schemas are correct: 
npx @modelcontextprotocol/inspector node build/index.js
Click on any tool to see its schema, required parameters, and test it interactively.

​
Contributing Guidelines

Read the full contributing guide

Learn about the contribution process, coding guidelines, and how to submit pull requests.

​
Quick Contributing Checklist

Before submitting a pull request:
  • Code follows existing style conventions
  • All linting and formatting checks pass (npm run precommit)
  • TypeScript compiles without errors (npm run build)
  • Changes are tested with MCP Inspector
  • Documentation is updated if needed
  • Commit messages follow conventional format

​
Branch Naming

# For new features
git checkout -b feature/your-feature-name

# For bug fixes
git checkout -b bugfix/issue-number-or-description

​
Commit Message Format

# New features
git commit -m "feat: Add new amazing feature"

# Bug fixes
git commit -m "fix: Resolve issue #123 by doing X"

# Documentation
git commit -m "docs: Update contributing guidelines"

# Refactoring
git commit -m "refactor: Simplify tool registration logic"

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us