# Coolify MCP Server

A robust TypeScript MCP (Model Context Protocol) server for integrating with Coolify, the self-hostable alternative to Netlify and Vercel.

## Features

- **Complete Coolify API Integration**: Manage applications, databases, servers, projects, and services
- **Type-Safe**: Full TypeScript support with comprehensive type definitions
- **MCP Protocol**: Compatible with Claude and other MCP clients
- **Resource Access**: Expose Coolify resources through MCP resource endpoints
- **Tool Support**: Comprehensive set of tools for Coolify operations

## Installation

```bash
npm install
npm run build
```

## Configuration

### Environment Variables

The server requires environment variables to connect to your Coolify instance:

```bash
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="optional-team-id"  # Optional
```

Or create a `.env` file:
```env
COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-api-token-here
COOLIFY_TEAM_ID=optional-team-id
```

### MCP Client Configuration

#### Claude Desktop

Add the server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp-server/dist/index.js"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}
```

#### Alternative: NPX Usage

If you publish to npm, users can run via npx:

```json
{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["@joshuarileydev/coolify-mcp-server", "--yes"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}
```

Or use the executable name directly:

```json
{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["coolify-mcp-server", "--yes"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}
```

#### Development Setup

For development, you can use the TypeScript source directly:

```json
{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["tsx", "/path/to/coolify-mcp-server/src/index.ts"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}
```

#### Other MCP Clients

For other MCP clients that support environment variables, ensure the following variables are set:

- `COOLIFY_API_URL` (required)
- `COOLIFY_API_TOKEN` (required)  
- `COOLIFY_TEAM_ID` (optional)

**Example shell script:**
```bash
#!/bin/bash
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="your-team-id"

node /path/to/coolify-mcp-server/dist/index.js
```

### Available Tools

#### Applications
- `list_applications` - List all applications
- `get_application` - Get application details
- `create_application` - Create new application
- `start_application` - Start an application
- `stop_application` - Stop an application  
- `restart_application` - Restart an application
- `deploy_application` - Deploy an application

#### Databases
- `list_databases` - List all databases
- `create_database` - Create new database

#### Servers
- `list_servers` - List all servers
- `create_server` - Create new server
- `validate_server` - Validate server connection

#### Projects
- `list_projects` - List all projects
- `create_project` - Create new project

#### Services
- `list_services` - List all services
- `start_service` - Start a service
- `stop_service` - Stop a service

#### System
- `get_version` - Get Coolify version

### Available Resources

The server exposes these MCP resources:

- `coolify://applications` - All applications
- `coolify://databases` - All databases  
- `coolify://servers` - All servers
- `coolify://projects` - All projects
- `coolify://services` - All services
- `coolify://teams` - All teams

## API Token Setup

1. Log into your Coolify instance
2. Navigate to "Keys & Tokens" > "API tokens"
3. Click "Create New Token"
4. Choose appropriate permissions:
   - `read-only`: Read data only
   - `read:sensitive`: Read with sensitive data
   - `*`: Full access (recommended for MCP server)
5. Copy the generated token

### Security Note

When using the MCP server with Claude Desktop or other clients, your API token will be stored in the configuration file. Ensure this file has appropriate permissions:

```bash
# macOS/Linux
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or set environment variables in your shell profile instead
echo 'export COOLIFY_API_TOKEN="your-token-here"' >> ~/.bashrc
```

## Development

```bash
# Install dependencies
npm install

# Run in development mode (requires env vars)
COOLIFY_API_URL=http://localhost:8000 COOLIFY_API_TOKEN=your-token npm run dev

# Build for production
npm run build

# Run built version
npm start

# Lint code
npm run lint

# Type check
npm run typecheck
```

## Troubleshooting

### Common Issues

1. **"COOLIFY_API_URL and COOLIFY_API_TOKEN environment variables are required"**
   - Ensure environment variables are set before starting the server
   - Check that your `.env` file is in the correct location
   - Verify variable names are spelled correctly

2. **"Tool execution failed: Request failed"**
   - Verify your Coolify instance is running and accessible
   - Check that the API URL is correct (include protocol: `http://` or `https://`)
   - Ensure your API token has the necessary permissions

3. **MCP server not appearing in Claude Desktop**
   - Restart Claude Desktop after updating configuration
   - Check the configuration file path is correct for your OS
   - Verify JSON syntax in the configuration file

### Debug Mode

To see detailed error messages, run the server with debug output:

```bash
DEBUG=* node dist/index.js
```

## License

MIT