Coolify MCP Server

Instructions

Implementation Reference

• src/tools/documentation-unified.ts:44-118 (handler)

  Main handler function that processes input parameters and calls appropriate CoolifyApiClient documentation methods based on the 'action' parameter.
  export async function handleDocumentation( coolifyClient: CoolifyApiClient, args: any ): Promise<any> { try { const { action, query, category, limit } = args; let result; let message; switch (action) { case 'search': result = await coolifyClient.searchDocumentation(query, category, limit || 10); message = `Found ${result.entries.length} documentation entries for "${query}"`; break; case 'get': result = await coolifyClient.getDocumentation(query, category); message = `Found ${result.length} documentation entries for topic "${query}"`; break; case 'api': result = await coolifyClient.getApiReference(query); message = query ? `API documentation for endpoint "${query}"` : 'Complete Coolify API reference documentation'; break; case 'troubleshoot': result = await coolifyClient.getTroubleshooting(query); message = `Found ${result.length} troubleshooting guides for "${query}"`; break; case 'topics': result = await coolifyClient.getDocumentationTopics(); message = `Available documentation topics`; break; case 'api_reference': result = await coolifyClient.getApiReference(query); message = query ? `API reference for "${query}"` : 'Complete Coolify API reference'; break; default: throw new Error(`Unknown documentation action: ${action}`); } return { content: [ { type: 'text', text: JSON.stringify({ success: true, data: result, message: message }, null, 2) } ] }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : 'Unknown error occurred' }, null, 2) } ], isError: true }; } }
• src/tools/documentation-unified.ts:13-42 (schema)

  Tool definition with name, description, and detailed inputSchema specifying parameters and validation rules.
  export const documentationTool: Tool = { name: 'coolify_documentation', description: 'Access Coolify documentation: search docs, get topic info, API reference, or troubleshooting guides', inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['search', 'get', 'api', 'troubleshoot', 'topics', 'api_reference'], description: 'Action to perform: search docs, get topic docs, get API reference, get troubleshooting, list topics, or get API reference', }, query: { type: 'string', description: 'Search query, topic name, API endpoint, or issue description', }, category: { type: 'string', description: 'Optional category filter (api, guide, configuration, troubleshooting)', }, limit: { type: 'number', description: 'Maximum number of results to return', default: 10, minimum: 1, maximum: 50, }, }, required: ['action', 'query'], }, };
• src/index.ts:125-134 (registration)

  Registers the documentationTool in the MCP server's list of available tools.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ applicationManagementTool, environmentConfigurationTool, systemManagementTool, documentationTool, ], }; });
• src/index.ts:159-160 (registration)

  Switch case in CallToolRequest handler that routes 'coolify_documentation' calls to the handleDocumentation function.
  case 'coolify_documentation': return await handleDocumentation(this.coolifyClient, args);
• src/utils/coolify-client.ts:306-637 (helper)

  Provides the built-in documentation database used by all documentation-related methods in CoolifyApiClient.
  private getBuiltInDocumentation(): DocumentationEntry[] { return [ // API Documentation { id: 'api-authentication', title: 'API Authentication', category: 'api', tags: ['api', 'authentication', 'token', 'bearer'], content: `# API Authentication To authenticate with the Coolify API, you need to include a Bearer token in your requests: ## Header Format \`\`\` Authorization: Bearer <your-api-token> \`\`\` ## Getting an API Token 1. Go to your Coolify dashboard 2. Navigate to Settings → Keys & Tokens → API Tokens 3. Click "Create New Token" 4. Define a name for your token 5. Select appropriate permissions: - \`read-only\`: Read data only - \`read:sensitive\`: Read including sensitive data - \`*\`: Full access (recommended for automation) ## Token Scopes - Tokens are scoped to the team that created them - Each token has specific permissions - Tokens are shown only once upon creation ## API Endpoints - Base URL: \`http://<your-coolify-instance>/api/v1\` - Health check: \`/health\` (no authentication required)`, url: 'https://coolify.io/docs/api' }, { id: 'api-applications', title: 'Applications API', category: 'api', tags: ['api', 'applications', 'deploy', 'manage'], content: `# Applications API ## List Applications \`GET /applications\` Returns all applications accessible to your token. ## Get Application \`GET /applications/{id}\` Returns detailed information about a specific application. ## Deploy Application \`POST /applications/{id}/deploy\` Triggers a new deployment. Optional parameters: - \`force\`: boolean - Force deployment even if another is in progress - \`branch\`: string - Deploy specific git branch ## Start/Stop/Restart Application - \`POST /applications/{id}/start\` - \`POST /applications/{id}/stop\` - \`POST /applications/{id}/restart\` ## Environment Variables - \`GET /applications/{id}/environment-variables\` - \`PUT /applications/{id}/environment-variables\` ## Logs \`GET /applications/{id}/logs?lines=100&since=2024-01-01T00:00:00Z\``, url: 'https://coolify.io/docs/api' }, // Deployment Guides { id: 'guide-deployment', title: 'Application Deployment Guide', category: 'guide', tags: ['deployment', 'guide', 'getting-started', 'applications'], content: `# Application Deployment Guide ## Prerequisites 1. Coolify instance running 2. Server connected to Coolify 3. Git repository accessible 4. Domain configured (optional) ## Step-by-Step Deployment ### 1. Create Application 1. Go to Projects → Create New Application 2. Select deployment method: - Git Repository - Docker Image - Docker Compose ### 2. Configure Repository - Repository URL - Branch (default: main) - Build pack (Nixpacks, Dockerfile, etc.) ### 3. Environment Variables Set necessary environment variables: - Database connections - API keys - Application settings ### 4. Domain Configuration - Set FQDN (Fully Qualified Domain Name) - Enable HTTPS/SSL (recommended) - Configure custom domains ### 5. Deploy Click "Deploy" to start the deployment process ## Build Packs - **Nixpacks**: Auto-detects and builds most applications - **Dockerfile**: Uses your custom Dockerfile - **Docker Compose**: For multi-service applications`, url: 'https://coolify.io/docs/applications' }, { id: 'guide-environment-variables', title: 'Environment Variables Guide', category: 'guide', tags: ['environment', 'variables', 'configuration', 'secrets'], content: `# Environment Variables Guide ## Predefined Variables Coolify automatically provides these variables: - \`COOLIFY_FQDN\`: Application's domain name - \`COOLIFY_URL\`: Application's URL(s) - \`COOLIFY_CONTAINER_NAME\`: Container name - \`COOLIFY_RESOURCE_UUID\`: Unique resource ID - \`SOURCE_COMMIT\`: Git commit hash - \`PORT\`: Application port (defaults to first exposed port) - \`HOST\`: Defaults to 0.0.0.0 ## Custom Variables Set custom environment variables for your application: ### Build-time Variables Available during the build process: - \`NODE_ENV=production\` - \`API_URL=https://api.example.com\` ### Runtime Variables Available when the application runs: - \`DATABASE_URL=postgresql://...\` - \`REDIS_URL=redis://...\` ### Sensitive Variables Mark variables as sensitive to hide them in the UI: - API keys - Passwords - Tokens ## Usage Example \`\`\`bash # Use predefined variables MY_VARIABLE=$SOURCE_COMMIT # Database configuration DB_CONNECTION=postgresql DB_HOST=postgres.example.com DB_PORT=5432 DB_DATABASE=myapp DB_USERNAME=user DB_PASSWORD=secret \`\`\``, url: 'https://coolify.io/docs/knowledge-base/environment-variables' }, // Configuration { id: 'config-domains-ssl', title: 'Domain and SSL Configuration', category: 'configuration', tags: ['domain', 'ssl', 'https', 'certificates'], content: `# Domain and SSL Configuration ## Setting Up Domains ### 1. Configure FQDN Set the Fully Qualified Domain Name for your application: - \`app.yourdomain.com\` - \`subdomain.example.org\` ### 2. DNS Configuration Point your domain to your server: - A record: \`app.yourdomain.com → 1.2.3.4\` - CNAME record: \`app.yourdomain.com → your-server.example.com\` ### 3. SSL/HTTPS Setup Coolify automatically handles SSL certificates using Let's Encrypt: #### Automatic SSL - Enable HTTPS in application settings - Coolify requests Let's Encrypt certificate - Auto-renewal handled automatically #### Custom Certificates Upload your own SSL certificates: 1. Go to application settings 2. Upload certificate files 3. Configure SSL settings ## Wildcard Certificates For multiple subdomains: \`\`\` *.yourdomain.com \`\`\` ## Traefik Configuration Coolify uses Traefik as reverse proxy: - Automatic SSL termination - Load balancing - Request routing`, url: 'https://coolify.io/docs/knowledge-base' }, // Troubleshooting { id: 'troubleshoot-deployment-failed', title: 'Deployment Failed', category: 'troubleshooting', tags: ['deployment', 'failed', 'build', 'error'], content: `# Troubleshooting: Deployment Failed ## Common Causes and Solutions ### 1. Build Errors **Symptoms**: Build process fails, error in build logs **Solutions**: - Check build logs for specific errors - Verify dependencies in package.json/requirements.txt - Ensure correct Node.js/Python version - Check for syntax errors in code ### 2. Port Configuration **Symptoms**: Application builds but not accessible **Solutions**: - Verify application listens on correct port - Use \`PORT\` environment variable: \`app.listen(process.env.PORT || 3000)\` - Check if port is exposed in Dockerfile ### 3. Environment Variables **Symptoms**: Application crashes or behaves unexpectedly **Solutions**: - Verify all required environment variables are set - Check for typos in variable names - Ensure sensitive variables are properly configured ### 4. Memory/Resource Limits **Symptoms**: Build process killed, out of memory errors **Solutions**: - Increase server resources - Optimize build process - Use multi-stage Docker builds - Clear build cache ### 5. Git Repository Issues **Symptoms**: Cannot clone repository, authentication errors **Solutions**: - Verify repository URL - Check deploy key permissions - Ensure repository is accessible - Verify branch name`, url: 'https://coolify.io/docs/knowledge-base' }, { id: 'troubleshoot-ssl-issues', title: 'SSL Certificate Issues', category: 'troubleshooting', tags: ['ssl', 'certificate', 'https', 'letsencrypt'], content: `# Troubleshooting: SSL Certificate Issues ## Common SSL Problems ### 1. Let's Encrypt Rate Limits **Symptoms**: Certificate generation fails, rate limit errors **Solutions**: - Wait for rate limit reset (1 week for duplicate certificates) - Use staging environment for testing - Check Let's Encrypt status page ### 2. Domain Verification Failed **Symptoms**: Certificate cannot be issued, domain verification fails **Solutions**: - Verify DNS records point to correct server - Check domain is accessible via HTTP first - Ensure port 80 is open and accessible - Wait for DNS propagation (up to 48 hours) ### 3. Certificate Renewal Issues **Symptoms**: Certificate expires, renewal fails **Solutions**: - Check Coolify logs for renewal errors - Verify domain still points to server - Manually trigger certificate renewal - Check server disk space ### 4. Mixed Content Warnings **Symptoms**: Browser warnings, some content not secure **Solutions**: - Ensure all resources use HTTPS URLs - Update API endpoints to use HTTPS - Check for hardcoded HTTP links in code ### 5. Certificate Chain Issues **Symptoms**: Browser shows certificate errors **Solutions**: - Use SSL checker tools to verify certificate chain - Check intermediate certificates - Contact certificate provider`, url: 'https://coolify.io/docs/knowledge-base' } ]; }