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](https://my.vultr.com/settings/#settingsapi))

### Setup

1. Clone the repository:
   ```bash
   git clone <repository-url>
   cd vultr-mcp-server
   ```

2. Create virtual environment and install dependencies:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   ```

3. Configure environment variables:
   ```bash
   cp .env.example .env
   # Edit .env and add your VULTR_API_KEY
   ```

4. Run the server:
   ```bash
   python main.py
   ```

## Configuration

### Environment Variables

Create a `.env` file with the following:

```env
# 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
```

### Getting Vultr API Key

1. Log in to your Vultr account
2. Go to [API Settings](https://my.vultr.com/settings/#settingsapi)
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

```bash
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

### Example API Calls

#### Using curl

```bash
# 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

```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):

```json
{
  "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:

```json
{
  "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:

```bash
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](https://github.com/yourusername/vultr-mcp-server/issues)
- Documentation: [Vultr API Docs](https://docs.vultr.com/api/)
- MCP Protocol: [Model Context Protocol](https://modelcontextprotocol.io)