# Devil MCP Server

A **Model Context Protocol (MCP) server** that provides programmatic access to devil hosting platform management tools through a secure REST API interface.

## Description

Devil MCP Server is a comprehensive solution that bridges the gap between AI assistants and devil hosting platform management. It consists of two main components:

- [**Devil API**](https://github.com/devil-imps/devil-api): A FastAPI-based REST API that communicates with the devil command-line tool via UNIX domain sockets
- **Devil MCP Server**: An MCP server wrapper that exposes the Devil API functionality to AI assistants and other MCP-compatible clients

This allows AI assistants to manage hosting services including websites, databases, DNS records, SSL certificates, email accounts, and more through a standardized protocol.

## Installation

Prerequisites:
- Python 3.11+
- A devil service available via UNIX domain socket at /var/run/devil2.sock (running on the same host)
- A valid API key to configure in your environment

1. Clone the repository
   ```sh
   git clone --recurse-submodules https://github.com/devil-imps/devil-mcp.git
   cd devil-mcp
   ```

2. Installation

   a) Using [UV](https://docs.astral.sh/uv/) (recommended)
   > Unfortunately, currently there is no UV installed on devil servers, you can use [Lilith: Devil's Package Manager](https://github.com/devil-imps/helpers/tree/inferno/lilith) to install UV.
   ```sh
   uv sync
   ```

   b) Using PIP editable install
   ```sh
   # Create and activate a virtual environment
   virtualenv .venv
   source .venv/bin/activate

   # Install dependencies
   pip install -e src/devil_api
   pip install -e .
   ```

3. Set up environment variables:
   ```sh
   cp .env.example .env
   ```
   
   Edit `.env` and configure your settings:
   ```env
   # Required API KEY, put here something strong
   DEVIL_API_KEY=your_devil_api_key_here

   # Devil MCP Server Configuration
   DEVIL_MCP_HOST=0.0.0.0
   # Change port number to your reserved port, use `devil port add tcp random devil-mcp` to reserve random one
   DEVIL_MCP_PORT=8000

   # Optional configurations
   READ_ONLY_MODE=false
   RATE_LIMIT_ENABLED=false
   RATE_LIMIT_MAX_REQUESTS=60
   RATE_LIMIT_WINDOW_MINUTES=1

   # Logging
   LOG_LEVEL=INFO
   ```

## Usage

### Starting the Server

#### Using UV:
```sh
# Installed script
uv run devil-mcp

# Or standalone script
uv run python run_server.py
```

#### Using virtualenv:
```sh
# Activate a virtual environment
source .venv/bin/activate

# Installed script
devil-mcp

# Or standalone script
python run_server.py
```

### Configuration Options

The server can be configured through environment variables:

```sh
# Server Configuration
export DEVIL_MCP_HOST="0.0.0.0"        # Bind to all interfaces
export DEVIL_MCP_PORT="8080"           # Custom port
export DEVIL_API_KEY="your-api-key"    # Required API key

# Security Options
export READ_ONLY_MODE="true"           # Enable read-only mode
export RATE_LIMIT_ENABLED="true"       # Enable rate limiting
export RATE_LIMIT_MAX_REQUESTS="100"   # Max requests per window
export RATE_LIMIT_WINDOW_MINUTES="5"   # Rate limit window

# Logging
export LOG_LEVEL="DEBUG"               # Set log level
```

## Connecting to AI Assistants & IDEs

The Devil MCP Server can be integrated with various AI assistants and development environments that support the Model Context Protocol (MCP).

### **Visual Studio Code**

#### Using the MCP Extension

1. **Install the MCP extension** in VS Code
2. **Configure the server** in your VS Code settings or MCP configuration file:

```json
{
  "servers": {
    "devil-mcp": {
      "type": "http",
      "url": "http://domain.tld:8000/mcp",
      "headers": {
        "Authorization": "Bearer your_devil_api_key_here"
      }
    }
  }
}
```

### **Claude Desktop**

See [Claude Desktop Quickstart](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server)

### **Web-based AI Assistants**

For web-based AI assistants that support HTTP MCP connections:

```json
{
  "mcp_servers": [
    {
      "name": "devil-mcp",
      "type": "http",
      "url": "http://domain.tld:8000/mcp",
      "auth": {
        "type": "bearer",
        "token": "your_devil_api_key_here"
      }
    }
  ]
}
```

## Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page or submit a pull request.

## License

This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE License. See the [LICENSE](LICENSE) file for details.