Devil 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: 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

   git clone --recurse-submodules https://github.com/devil-imps/devil-mcp.git
   cd devil-mcp
   

2. Installation

   a) Using UV (recommended)

   Unfortunately, currently there is no UV installed on devil servers, you can use Lilith: Devil's Package Manager to install UV.

   uv sync
   

   b) Using PIP editable install

   # 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:

   cp .env.example .env
   

   Edit .env and configure your settings:

   # 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:

# Installed script
uv run devil-mcp

# Or standalone script
uv run python run_server.py

Using virtualenv:

# 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:

# 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:

{
  "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

Web-based AI Assistants

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

{
  "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 file for details.