mcp-vultr/README.md

Vultr MCP Server

Model Context Protocol (MCP) Server for Vultr Cloud Services

Overview

This MCP server provides AI applications with access to Vultr cloud services through the Model Context Protocol. It enables AI assistants to manage Vultr infrastructure including instances, storage, networking, and more.

Features

• Account Management: Get account information and balance
• Instance Management: Create, list, start, stop, reboot, and delete instances
• Resource Discovery: List available regions, plans, and operating systems
• MCP Protocol Compliance: Full implementation of MCP v0.2+ protocol
• FastAPI Backend: High-performance async API server

Installation

Prerequisites

• Python 3.8+
• Vultr API key (from Vultr API Settings)

Setup

1. Clone the repository:

   git clone <repository-url>
   cd vultr-mcp-server
   

2. Create virtual environment and install dependencies:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env and add your VULTR_API_KEY
   

4. Run the server:

   python main.py
   

Configuration

Environment Variables

Create a .env file with the following:

# Vultr API Key (required)
VULTR_API_KEY=your_vultr_api_key_here

# Server Configuration (optional)
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=info

# Billing Database Configuration (optional, for billing tools)
# Single server format:
BILLING_DB_HOST=localhost
BILLING_DB_USER=root
BILLING_DB_PASS=password
BILLING_DB_NAME=billing_db

# Multiple servers format (BILLING_DB_1_, BILLING_DB_2_, etc.):
# BILLING_DB_1_HOST=server1.example.com
# BILLING_DB_1_USER=user1
# BILLING_DB_1_PASS=pass1
# BILLING_DB_1_NAME=db1
# BILLING_DB_1_ALIAS="Primary Server"
# BILLING_DB_2_HOST=server2.example.com
# BILLING_DB_2_USER=user2
# BILLING_DB_2_PASS=pass2
# BILLING_DB_2_NAME=db2
# BILLING_DB_2_ALIAS="Backup Server"

Getting Vultr API Key

1. Log in to your Vultr account
2. Go to API Settings
3. Click "Enable API" if not already enabled
4. Generate a new API key or use an existing one
5. Copy the API key to your .env file

Usage

Starting the Server

python main.py

The server will start on http://0.0.0.0:8000 by default.

MCP Endpoints

• GET / - Server information
• GET /tools - List available tools
• GET /resources - List available resources
• GET /prompts - List available prompts
• POST /tools/call - Execute a tool
• GET /resources/{uri} - Get resource content

Available Tools

Account Management

• get_account_info - Get Vultr account information

Instance Management

• list_instances - List all Vultr instances
• get_instance - Get details of a specific instance
• create_instance - Create a new Vultr instance
• delete_instance - Delete a Vultr instance
• start_instance - Start a Vultr instance
• stop_instance - Stop a Vultr instance
• reboot_instance - Reboot a Vultr instance

Resource Discovery

• list_regions - List available Vultr regions
• list_plans - List available Vultr plans
• list_os - List available Vultr operating systems

Billing Database Management

• billing_check_connection - Check billing database connection
• billing_list_servers - List configured billing database servers and snapshot status
• billing_refresh_snapshot - Update the local data snapshot from the live database
• billing_search_customers - Search customers from the local snapshot
• billing_get_customer_details - Get detailed customer information from the local snapshot
• billing_get_summary - Get customer statistics summary from the local snapshot

Example API Calls

Using curl

# List available tools
curl http://localhost:8000/tools

# Get account info
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_account_info", "arguments": {}}'

# List instances
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "list_instances", "arguments": {"per_page": 10}}'

# Create an instance
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_instance",
    "arguments": {
      "region": "ams",
      "plan": "vc2-1c-1gb",
      "os_id": 387,
      "label": "my-web-server",
      "hostname": "web1"
    }
  }'

Using Python

import requests
import json

# List tools
response = requests.get("http://localhost:8000/tools")
print(json.dumps(response.json(), indent=2))

# Create instance
data = {
    "name": "create_instance",
    "arguments": {
        "region": "ams",
        "plan": "vc2-1c-1gb",
        "os_id": 387,
        "label": "test-server"
    }
}
response = requests.post("http://localhost:8000/tools/call", json=data)
print(json.dumps(response.json(), indent=2))

Integration with AI Applications

Claude Desktop

Add to Claude Desktop configuration (~/.config/claude/desktop_config.json on macOS/Linux):

{
  "mcpServers": {
    "vultr": {
      "command": "python",
      "args": [
        "/path/to/vultr-mcp-server/main.py"
      ],
      "env": {
        "VULTR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Add to Cursor MCP configuration:

{
  "mcpServers": {
    "vultr": {
      "command": "python",
      "args": [
        "/path/to/vultr-mcp-server/main.py"
      ],
      "env": {
        "VULTR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Development

Project Structure

vultr-mcp-server/
├── src/
│   ├── vultr_mcp/
│   │   ├── __init__.py
│   │   ├── client.py      # Vultr API client
│   │   └── server.py      # MCP server implementation
│   └── __init__.py
├── tests/                 # Test files
├── examples/              # Example usage
├── main.py               # Entry point
├── requirements.txt      # Dependencies
├── .env.example          # Environment template
└── README.md            # This file

Adding New Tools

1. Add tool definition in server.py in the list_tools() function
2. Implement tool logic in client.py
3. Add tool execution handler in call_tool() function in server.py

Testing

Run the test suite:

python -m pytest tests/

Security Considerations

• API Key Protection: Never commit .env file to version control
• Network Security: Run server on localhost or secure network
• Access Control: Implement authentication for production use
• Rate Limiting: Vultr API has rate limits (see Vultr documentation)

Limitations

• Requires valid Vultr API key with appropriate permissions
• Rate limited by Vultr API (typically 500 requests per hour)
• Some Vultr API endpoints not yet implemented

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Documentation: Vultr API Docs
• MCP Protocol: Model Context Protocol