Coolify MCP Server

Instructions

Implementation Reference

• src/index.ts:1434-1472 (handler)

  Handler implementation for the execute_command_application tool within the CallToolRequestSchema handler. Performs version check, API call to execute command in application container, and detailed error handling.
  case 'execute_command_application': // Check if execute command endpoint is available in this version if (!this.isFeatureAvailable('execute_command')) { return { content: [{ type: 'text', text: `Execute command endpoint not available in Coolify ${this.coolifyVersion?.version || 'this version'}. This feature requires Coolify v4.0.0-beta.400 or later.` }] }; } try { const executeResponse = await this.axiosInstance.post( `/applications/${request.params.arguments?.uuid}/execute`, { command: request.params.arguments?.command } ); return { content: [{ type: 'text', text: JSON.stringify(executeResponse.data, null, 2) }] }; } catch (error) { // Instead of throwing an error, return a message if (axios.isAxiosError(error) && error.response?.status === 404) { return { content: [{ type: 'text', text: `Execute command endpoint not available in Coolify ${this.coolifyVersion?.version || 'this version'} or the application UUID is invalid.` }] }; } else { // For other errors, provide more details return { content: [{ type: 'text', text: "Error executing command: " + (axios.isAxiosError(error) ? error.response?.data?.message || error.message : 'Unknown error') }] }; } }
• src/index.ts:968-1017 (schema)

  Tool schema definition including name, description, input schema with uuid and command parameters, examples, workflow, related tools, and notes. Registered in the ListToolsRequestSchema response.
  { name: 'execute_command_application', description: 'Execute a command inside a running application container. Useful for debugging, maintenance, or running one-off tasks. Note: This endpoint may not be available in all Coolify versions.', inputSchema: { type: 'object', properties: { uuid: { type: 'string', description: 'UUID of the application where the command will be executed. Get this from list_applications.', pattern: '^[a-zA-Z0-9]+$' }, command: { type: 'string', description: 'The command to execute inside the container. This can be any valid shell command.', examples: [ 'npm run migrations', 'python manage.py collectstatic', 'ls -la', 'cat /var/log/app.log' ] } }, required: ['uuid', 'command'], examples: [ { uuid: 'sg4gsws44wksg040o4ok80ww', command: 'npm run migrations' } ], additionalInfo: { workflow: [ '1. Ensure the application is running (use start_application if needed)', '2. Get the application UUID from list_applications', '3. Execute the desired command', '4. Check the command output in the response' ], relatedTools: [ 'list_applications - Get UUIDs of available applications', 'start_application - Ensure application is running', 'restart_application - Restart if needed' ], notes: [ 'The application must be running for commands to execute', 'Commands run in the application\'s container environment', 'Command execution is synchronous and will return the output', 'Use with caution as commands can modify the application state' ] } } },
• src/index.ts:1201-1528 (registration)

  Registration of the CallToolRequestSchema handler which contains the switch case dispatching to the execute_command_application implementation.
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => { if (!this.axiosInstance) { throw new McpError( ErrorCode.InvalidRequest, 'Coolify configuration not initialized. Please set COOLIFY_BASE_URL and COOLIFY_TOKEN environment variables.' ); } try { switch (request.params.name) { // Version & Health case 'get_version': const versionResponse = await this.axiosInstance.get('/version'); return { content: [{ type: 'text', text: JSON.stringify(versionResponse.data, null, 2) }] }; case 'health_check': // Check if health endpoint is available in this version if (!this.isFeatureAvailable('health_check')) { return { content: [{ type: 'text', text: `Health check endpoint not available in Coolify ${this.coolifyVersion?.version || 'this version'}.` }] }; } try { const healthResponse = await this.axiosInstance.get('/healthcheck'); return { content: [{ type: 'text', text: JSON.stringify(healthResponse.data, null, 2) }] }; } catch (error) { // Instead of throwing an error, return a message if (axios.isAxiosError(error) && error.response?.status === 404) { return { content: [{ type: 'text', text: `Health check endpoint not available in Coolify ${this.coolifyVersion?.version || 'this version'}.` }] }; } else { // For other errors, provide more details return { content: [{ type: 'text', text: "Error checking Coolify health: " + (axios.isAxiosError(error) ? error.response?.data?.message || error.message : 'Unknown error') }] }; } } // Teams case 'list_teams': const teamsResponse = await this.axiosInstance.get('/teams'); return { content: [{ type: 'text', text: JSON.stringify(teamsResponse.data, null, 2) }] }; case 'get_team': const teamId = request.params.arguments?.team_id; if (!teamId) { throw new McpError(ErrorCode.InvalidParams, 'team_id is required'); } const teamResponse = await this.axiosInstance.get(`/teams/${teamId}`); return { content: [{ type: 'text', text: JSON.stringify(teamResponse.data, null, 2) }] }; case 'get_current_team': const currentTeamResponse = await this.axiosInstance.get('/teams/current'); return { content: [{ type: 'text', text: JSON.stringify(currentTeamResponse.data, null, 2) }] }; case 'get_current_team_members': const currentTeamMembersResponse = await this.axiosInstance.get('/teams/current/members'); return { content: [{ type: 'text', text: JSON.stringify(currentTeamMembersResponse.data, null, 2) }] }; // Servers case 'list_servers': const serversResponse = await this.axiosInstance.get('/servers'); return { content: [{ type: 'text', text: JSON.stringify(serversResponse.data, null, 2) }] }; case 'create_server': const createServerResponse = await this.axiosInstance.post('/servers', request.params.arguments); return { content: [{ type: 'text', text: JSON.stringify(createServerResponse.data, null, 2) }] }; case 'validate_server': const validateServerResponse = await this.axiosInstance.get(`/servers/${request.params.arguments?.uuid}/validate`); return { content: [{ type: 'text', text: JSON.stringify(validateServerResponse.data, null, 2) }] }; case 'get_server_resources': const serverResourcesResponse = await this.axiosInstance.get(`/servers/${request.params.arguments?.uuid}/resources`); return { content: [{ type: 'text', text: JSON.stringify(serverResourcesResponse.data, null, 2) }] }; case 'get_server_domains': const serverDomainsResponse = await this.axiosInstance.get(`/servers/${request.params.arguments?.uuid}/domains`); return { content: [{ type: 'text', text: JSON.stringify(serverDomainsResponse.data, null, 2) }] }; // Projects case 'list_projects': const projectsResponse = await this.axiosInstance.get('/projects'); return { content: [{ type: 'text', text: JSON.stringify(projectsResponse.data, null, 2) }] }; case 'get_project': const projectUuid = request.params.arguments?.project_uuid; if (!projectUuid) { throw new McpError(ErrorCode.InvalidParams, 'project_uuid is required'); } const projectResponse = await this.axiosInstance.get(`/projects/${projectUuid}`); return { content: [{ type: 'text', text: JSON.stringify(projectResponse.data, null, 2) }] }; case 'create_project': const createProjectResponse = await this.axiosInstance.post('/projects', request.params.arguments); return { content: [{ type: 'text', text: JSON.stringify(createProjectResponse.data, null, 2) }] }; // Environments case 'list_environments': const envProjectUuid = request.params.arguments?.project_uuid; if (!envProjectUuid) { throw new McpError(ErrorCode.InvalidParams, 'project_uuid is required'); } const environmentsResponse = await this.axiosInstance.get(`/projects/${envProjectUuid}/environments`); return { content: [{ type: 'text', text: JSON.stringify(environmentsResponse.data, null, 2) }] }; case 'create_environment': const createEnvironmentResponse = await this.axiosInstance.post('/environments', request.params.arguments); return { content: [{ type: 'text', text: JSON.stringify(createEnvironmentResponse.data, null, 2) }] }; // Services case 'list_services': const servicesResponse = await this.axiosInstance.get('/services'); return { content: [{ type: 'text', text: JSON.stringify(servicesResponse.data, null, 2) }] }; case 'create_service': try { const createServiceResponse = await this.axiosInstance.post('/services', request.params.arguments); return { content: [{ type: 'text', text: JSON.stringify(createServiceResponse.data, null, 2) }] }; } catch (error) { if (axios.isAxiosError(error) && error.response) { const errorDetail = { status: error.response.status, statusText: error.response.statusText, data: error.response.data, requestUrl: error.config?.url, requestMethod: error.config?.method, requestData: request.params.arguments }; return { content: [{ type: 'text', text: `Service creation failed with detailed error:\n${JSON.stringify(errorDetail, null, 2)}` }] }; } throw error; } case 'start_service': const startServiceResponse = await this.axiosInstance.get(`/services/${request.params.arguments?.uuid}/start`); return { content: [{ type: 'text', text: JSON.stringify(startServiceResponse.data, null, 2) }] }; case 'stop_service': const stopServiceResponse = await this.axiosInstance.get(`/services/${request.params.arguments?.uuid}/stop`); return { content: [{ type: 'text', text: JSON.stringify(stopServiceResponse.data, null, 2) }] }; case 'restart_service': const restartServiceResponse = await this.axiosInstance.get(`/services/${request.params.arguments?.uuid}/restart`); return { content: [{ type: 'text', text: JSON.stringify(restartServiceResponse.data, null, 2) }] }; // Applications case 'list_applications': const applicationsResponse = await this.axiosInstance.get('/resources'); return { content: [{ type: 'text', text: JSON.stringify(applicationsResponse.data, null, 2) }] }; case 'create_application': const createApplicationResponse = await this.axiosInstance.post('/applications', request.params.arguments); return { content: [{ type: 'text', text: JSON.stringify(createApplicationResponse.data, null, 2) }] }; case 'start_application': const startAppResponse = await this.axiosInstance.get(`/applications/${request.params.arguments?.uuid}/start`); return { content: [{ type: 'text', text: JSON.stringify(startAppResponse.data, null, 2) }] }; case 'stop_application': const stopAppResponse = await this.axiosInstance.get(`/applications/${request.params.arguments?.uuid}/stop`); return { content: [{ type: 'text', text: JSON.stringify(stopAppResponse.data, null, 2) }] }; case 'restart_application': const restartAppResponse = await this.axiosInstance.get(`/applications/${request.params.arguments?.uuid}/restart`); return { content: [{ type: 'text', text: JSON.stringify(restartAppResponse.data, null, 2) }] }; case 'execute_command_application': // Check if execute command endpoint is available in this version if (!this.isFeatureAvailable('execute_command')) { return { content: [{ type: 'text', text: `Execute command endpoint not available in Coolify ${this.coolifyVersion?.version || 'this version'}. This feature requires Coolify v4.0.0-beta.400 or later.` }] }; } try { const executeResponse = await this.axiosInstance.post( `/applications/${request.params.arguments?.uuid}/execute`, { command: request.params.arguments?.command } ); return { content: [{ type: 'text', text: JSON.stringify(executeResponse.data, null, 2) }] }; } catch (error) { // Instead of throwing an error, return a message if (axios.isAxiosError(error) && error.response?.status === 404) { return { content: [{ type: 'text', text: `Execute command endpoint not available in Coolify ${this.coolifyVersion?.version || 'this version'} or the application UUID is invalid.` }] }; } else { // For other errors, provide more details return { content: [{ type: 'text', text: "Error executing command: " + (axios.isAxiosError(error) ? error.response?.data?.message || error.message : 'Unknown error') }] }; } } case 'get_application_logs': const uuid = request.params.arguments?.uuid; const lines = request.params.arguments?.lines || 100; if (!uuid) { throw new McpError(ErrorCode.InvalidParams, 'uuid is required'); } const logsResponse = await this.axiosInstance.get(`/applications/${uuid}/logs`, { params: { lines } }); return { content: [{ type: 'text', text: JSON.stringify(logsResponse.data, null, 2) }] }; // Deployments case 'list_deployments': const deploymentsResponse = await this.axiosInstance.get('/deployments'); return { content: [{ type: 'text', text: JSON.stringify(deploymentsResponse.data, null, 2) }] }; case 'get_deployment': const deploymentResponse = await this.axiosInstance.get(`/deployments/${request.params.arguments?.uuid}`); return { content: [{ type: 'text', text: JSON.stringify(deploymentResponse.data, null, 2) }] }; // Private Keys case 'list_private_keys': const privateKeysResponse = await this.axiosInstance.get('/security/keys'); return { content: [{ type: 'text', text: JSON.stringify(privateKeysResponse.data, null, 2) }] }; case 'create_private_key': const createPrivateKeyResponse = await this.axiosInstance.post('/security/keys', request.params.arguments); return { content: [{ type: 'text', text: JSON.stringify(createPrivateKeyResponse.data, null, 2) }] }; default: throw new McpError( ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}` ); } } catch (error) { if (axios.isAxiosError(error)) { throw new McpError( ErrorCode.InternalError, `Coolify API error: ${error.response?.data?.message || error.message}` ); } throw error; } });
• src/index.ts:113-120 (helper)

  isFeatureAvailable helper method checks if 'execute_command' feature is available based on Coolify version (beta.400+), used in the tool handler.
  case 'execute_command': return beta ? beta >= 400 : major >= 4; // Available from beta.400+ case 'application_logs': return beta ? beta >= 380 : major >= 4; // Available from beta.380+ default: return true; // Assume other features are available } }