mcp-vultr

Name	mcp-vultr JSON
Version	1.9.0 JSON
	download
home_page	None
Summary	A comprehensive Model Context Protocol (MCP) server for managing Vultr DNS records
upload_time	2025-08-06 00:39:22
maintainer	None
docs_url	None
author	None
requires_python	>=3.10
license	MIT
keywords	vultr dns mcp model-context-protocol dns-management api mcp-server
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Vultr MCP

A comprehensive Model Context Protocol (MCP) server for managing Vultr services through natural language interfaces.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

## Features

- **Complete MCP Server**: Full Model Context Protocol implementation with 70+ tools across 8 service modules
- **Comprehensive Service Coverage**: 
  - **DNS Management**: Full DNS record management (A, AAAA, CNAME, MX, TXT, NS, SRV)
  - **Instance Management**: Create, manage, and control compute instances
  - **SSH Keys**: Manage SSH keys for secure access
  - **Backups**: Create and manage instance backups
  - **Firewall**: Configure firewall groups and rules
  - **Snapshots**: Create and manage instance snapshots
  - **Regions**: Query region availability and capabilities
  - **Reserved IPs**: Manage static IP addresses
- **Smart Identifier Resolution**: Use human-readable names instead of UUIDs (e.g., "web-server" instead of UUID)
- **Zone File Import/Export**: Standard zone file format support for bulk DNS operations
- **Intelligent Validation**: Pre-creation validation with helpful suggestions
- **CLI Interface**: Complete command-line tool for direct operations
- **High-Level Client**: Convenient Python API for common operations
- **Modern Development**: Fast development workflow with uv support

## Smart Identifier Resolution

One of the key features is **automatic UUID lookup** across all services. Instead of requiring UUIDs, you can use human-readable identifiers:

- **Instances**: Use label or hostname instead of UUID
- **SSH Keys**: Use key name instead of UUID  
- **Firewall Groups**: Use description instead of UUID
- **Snapshots**: Use description instead of UUID
- **Reserved IPs**: Use IP address instead of UUID

### Examples

```bash
# Traditional approach (with UUIDs)
mcp-vultr instances stop cb676a46-66fd-4dfb-b839-443f2e6c0b60
mcp-vultr firewall rules list 5f2a4b6c-7b8d-4e9f-a1b2-3c4d5e6f7a8b

# Smart approach (with names)
mcp-vultr instances stop web-server
mcp-vultr firewall rules list production-servers
```

The system uses **exact matching** to ensure safety - if multiple resources have similar names, you'll get an error rather than operating on the wrong resource.

## Quick Start

### Installation

```bash
# Using uv (recommended - fast and modern)
uv add mcp-vultr

# Or using pip
pip install mcp-vultr
```

### Basic Usage

```bash
# Set your Vultr API key
export VULTR_API_KEY="your-api-key"

# DNS Management
mcp-vultr domains list
mcp-vultr records list example.com
mcp-vultr setup-website example.com 192.168.1.100

# Instance Management (with smart name resolution)
mcp-vultr instances list
mcp-vultr instances get web-server  # Uses name instead of UUID
mcp-vultr instances stop web-server

# SSH Key Management
mcp-vultr ssh-keys list
mcp-vultr ssh-keys add "laptop" "ssh-rsa AAAAB3..."

# Firewall Management
mcp-vultr firewall groups list
mcp-vultr firewall rules list web-servers  # Uses description instead of UUID

# Run as MCP server
vultr-mcp-server
```

### Python API

```python
import asyncio
from mcp_vultr import VultrDNSClient, VultrDNSServer

async def main():
    # DNS-specific client
    dns_client = VultrDNSClient("your-api-key")
    
    # List domains
    domains = await dns_client.domains()
    
    # Add DNS records
    await dns_client.add_a_record("example.com", "www", "192.168.1.100")
    await dns_client.add_mx_record("example.com", "@", "mail.example.com", 10)
    
    # Get domain summary
    summary = await dns_client.get_domain_summary("example.com")
    print(f"Domain has {summary['total_records']} records")
    
    # Full API client for all services
    vultr = VultrDNSServer("your-api-key")
    
    # Smart identifier resolution - use names instead of UUIDs!
    instance = await vultr.get_instance("web-server")  # By label
    ssh_key = await vultr.get_ssh_key("laptop-key")   # By name
    firewall = await vultr.get_firewall_group("production")  # By description
    snapshot = await vultr.get_snapshot("backup-2024-01")    # By description
    reserved_ip = await vultr.get_reserved_ip("192.168.1.100")  # By IP

asyncio.run(main())
```

### MCP Integration

This package provides a complete MCP server that can be integrated with MCP-compatible clients:

```python
from mcp_vultr import create_mcp_server, run_server

# Create server
server = create_mcp_server("your-api-key")

# Run server
await run_server("your-api-key")
```

## Development

### Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- Vultr API key

### Setup with uv (Recommended)

```bash
# Clone the repository
git clone https://github.com/rsp2k/mcp-vultr.git
cd mcp-vultr

# Install dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run comprehensive test suite
uv run python run_tests.py --all-checks

# Format code
uv run black src tests
uv run isort src tests

# Type checking
uv run mypy src
```

### Setup with pip (Traditional)

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .[dev]

# Run tests
pytest

# Run comprehensive test suite
python run_tests.py --all-checks
```

## MCP Tools Available

The MCP server provides 70+ tools across 8 service modules. All tools support **smart identifier resolution** - you can use human-readable names instead of UUIDs!

### DNS Management (12 tools)
- `dns_list_domains` - List all DNS domains
- `dns_get_domain` - Get domain details
- `dns_create_domain` - Create new domain
- `dns_delete_domain` - Delete domain and all records
- `dns_list_records` - List records for a domain
- `dns_create_record` - Create new DNS record
- `dns_update_record` - Update existing record
- `dns_delete_record` - Delete DNS record
- `dns_validate_record` - Validate record before creation
- `dns_analyze_records` - Analyze domain configuration
- `dns_import_zone_file` - Import DNS records from zone file
- `dns_export_zone_file` - Export DNS records to zone file

### Instance Management (9 tools)
- `instances_list` - List all instances
- `instances_get` - Get instance details (**smart**: by label, hostname, or UUID)
- `instances_create` - Create new instance
- `instances_update` - Update instance configuration
- `instances_delete` - Delete instance (**smart**: by label, hostname, or UUID)
- `instances_start` - Start a stopped instance (**smart**: by label, hostname, or UUID)
- `instances_stop` - Stop a running instance (**smart**: by label, hostname, or UUID)
- `instances_reboot` - Reboot instance (**smart**: by label, hostname, or UUID)
- `instances_reinstall` - Reinstall instance OS (**smart**: by label, hostname, or UUID)

### SSH Key Management (5 tools)
- `ssh_keys_list` - List all SSH keys
- `ssh_keys_get` - Get SSH key details (**smart**: by name or UUID)
- `ssh_keys_create` - Add new SSH key
- `ssh_keys_update` - Update SSH key (**smart**: by name or UUID)
- `ssh_keys_delete` - Remove SSH key (**smart**: by name or UUID)

### Backup Management (2 tools)
- `backups_list` - List all backups
- `backups_get` - Get backup details

### Firewall Management (10 tools)
- `firewall_list_groups` - List firewall groups
- `firewall_get_group` - Get group details (**smart**: by description or UUID)
- `firewall_create_group` - Create firewall group
- `firewall_update_group` - Update group description (**smart**: by description or UUID)
- `firewall_delete_group` - Delete firewall group (**smart**: by description or UUID)
- `firewall_list_rules` - List rules in a group (**smart**: by description or UUID)
- `firewall_get_rule` - Get specific rule (**smart**: group by description or UUID)
- `firewall_create_rule` - Add firewall rule (**smart**: group by description or UUID)
- `firewall_delete_rule` - Remove firewall rule (**smart**: group by description or UUID)
- `firewall_setup_web_server_rules` - Quick setup for web servers (**smart**: group by description or UUID)

### Snapshot Management (6 tools)
- `snapshots_list` - List all snapshots
- `snapshots_get` - Get snapshot details (**smart**: by description or UUID)
- `snapshots_create` - Create instance snapshot
- `snapshots_create_from_url` - Create snapshot from URL
- `snapshots_update` - Update snapshot description (**smart**: by description or UUID)
- `snapshots_delete` - Delete snapshot (**smart**: by description or UUID)

### Region Information (4 tools)
- `regions_list` - List all available regions
- `regions_get_availability` - Check plan availability in region
- `regions_find_regions_with_plan` - Find regions for specific plan
- `regions_list_by_continent` - Filter regions by continent

### Reserved IP Management (12 tools)
- `reserved_ips_list` - List all reserved IPs
- `reserved_ips_get` - Get reserved IP details (**smart**: by IP address or UUID)
- `reserved_ips_create` - Reserve new IP address
- `reserved_ips_update` - Update reserved IP label (**smart**: by IP address or UUID)
- `reserved_ips_delete` - Release reserved IP (**smart**: by IP address or UUID)
- `reserved_ips_attach` - Attach IP to instance (**smart**: by IP address or UUID)
- `reserved_ips_detach` - Detach IP from instance (**smart**: by IP address or UUID)
- `reserved_ips_convert_instance_ip` - Convert instance IP to reserved
- `reserved_ips_list_by_region` - List IPs in specific region
- `reserved_ips_list_unattached` - List unattached IPs
- `reserved_ips_list_attached` - List attached IPs with instance info

## CLI Commands

```bash
# Domain management
mcp-vultr domains list
mcp-vultr domains info example.com
mcp-vultr domains create newdomain.com 192.168.1.100

# Record management
mcp-vultr records list example.com
mcp-vultr records add example.com A www 192.168.1.100
mcp-vultr records delete example.com record-id

# Zone file operations
mcp-vultr zones export example.com > example.zone
mcp-vultr zones import example.com example.zone

# Instance management (with smart identifier resolution)
mcp-vultr instances list
mcp-vultr instances create --region ewr --plan vc2-1c-1gb --os 387 --label web-server
mcp-vultr instances get web-server            # By label
mcp-vultr instances stop production.local     # By hostname
mcp-vultr instances reboot web-server        # By label

# SSH key management (with smart identifier resolution)
mcp-vultr ssh-keys list
mcp-vultr ssh-keys add laptop-key "ssh-rsa AAAAB3..."
mcp-vultr ssh-keys delete laptop-key         # By name

# Firewall management (with smart identifier resolution)
mcp-vultr firewall groups list
mcp-vultr firewall groups create "web-servers"
mcp-vultr firewall rules list web-servers    # By description
mcp-vultr firewall rules add web-servers --port 443 --protocol tcp

# Snapshot management (with smart identifier resolution)
mcp-vultr snapshots list
mcp-vultr snapshots create instance-id --description "backup-2024-01"
mcp-vultr snapshots delete backup-2024-01    # By description

# Reserved IP management (with smart identifier resolution)
mcp-vultr reserved-ips list
mcp-vultr reserved-ips create --region ewr --type v4 --label production-ip
mcp-vultr reserved-ips attach 192.168.1.100 instance-id  # By IP
mcp-vultr reserved-ips delete 192.168.1.100             # By IP

# Setup utilities
mcp-vultr setup-website example.com 192.168.1.100
mcp-vultr setup-email example.com mail.example.com

# Start MCP server
vultr-mcp-server
```

## Testing

This project follows FastMCP testing best practices with comprehensive test coverage:

```bash
# Run all tests (uv)
uv run pytest

# Run specific test categories
uv run pytest -m unit          # Unit tests
uv run pytest -m integration   # Integration tests  
uv run pytest -m mcp          # MCP-specific tests

# With coverage
uv run pytest --cov=mcp_vultr --cov-report=html

# Full validation suite
uv run python run_tests.py --all-checks
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run the test suite (`uv run python run_tests.py --all-checks`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## Error Handling

The package provides specific exception types for better error handling:

```python
from mcp_vultr import (
    VultrAPIError,
    VultrAuthError,
    VultrRateLimitError,
    VultrResourceNotFoundError,
    VultrValidationError
)

try:
    await client.get_domain("example.com")
except VultrAuthError:
    print("Invalid API key or insufficient permissions")
except VultrResourceNotFoundError:
    print("Domain not found")
except VultrRateLimitError:
    print("Rate limit exceeded, please try again later")
except VultrAPIError as e:
    print(f"API error {e.status_code}: {e.message}")
```

## Configuration

Set your Vultr API key via environment variable:

```bash
export VULTR_API_KEY="your-vultr-api-key"
```

Or pass directly to the client:

```python
client = VultrDNSClient("your-api-key")
server = create_mcp_server("your-api-key")
```

## Changelog

### v1.9.0 (Latest)
- **Feature**: Universal UUID lookup pattern across all modules - use human-readable names everywhere!
  - Instances: lookup by label or hostname
  - SSH Keys: lookup by name
  - Firewall Groups: lookup by description
  - Snapshots: lookup by description
  - Reserved IPs: lookup by IP address
- **Feature**: All UUID lookups use exact matching for safety
- **Enhancement**: Improved error messages when resources not found

### v1.8.1
- **Feature**: Smart identifier resolution for Reserved IPs
- **Fix**: Reserved IP tools now accept IP addresses directly

### v1.8.0
- **Feature**: Complete Reserved IP management (12 new tools)
- **Feature**: Support for IPv4 and IPv6 reserved IPs
- **Feature**: Convert existing instance IPs to reserved

### v1.1.0
- **Feature**: Zone file import/export functionality
- **Feature**: Standard DNS zone file format support

### v1.0.1
- **Major**: Migrated to FastMCP 2.0 framework
- **Feature**: Custom exception hierarchy for better error handling
- **Feature**: Enhanced IPv6 validation with ipaddress module
- **Feature**: HTTP request timeouts (30s total, 10s connect)
- **Feature**: Full uv package manager integration
- **Fix**: Resolved event loop issues with FastMCP

### v1.0.0
- Initial release with complete MCP server implementation
- Support for DNS, Instances, SSH Keys, Backups, Firewall, Snapshots, Regions
- CLI interface and Python client library

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Links

- [GitHub Repository](https://github.com/rsp2k/mcp-vultr)
- [PyPI Package](https://pypi.org/project/mcp-vultr/)
- [Vultr API Documentation](https://www.vultr.com/api/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [uv Package Manager](https://docs.astral.sh/uv/)

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "mcp-vultr",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": "Ryan Malloy <ryan@supported.systems>",
    "keywords": "vultr, dns, mcp, model-context-protocol, dns-management, api, mcp-server",
    "author": null,
    "author_email": "Ryan Malloy <ryan@supported.systems>",
    "download_url": "https://files.pythonhosted.org/packages/87/82/5f39368f347c653da48626f10ec256b1d67cee3bb966bd35864cbcc35e08/mcp_vultr-1.9.0.tar.gz",
    "platform": null,
    "description": "# Vultr MCP\n\nA comprehensive Model Context Protocol (MCP) server for managing Vultr services through natural language interfaces.\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)\n\n## Features\n\n- **Complete MCP Server**: Full Model Context Protocol implementation with 70+ tools across 8 service modules\n- **Comprehensive Service Coverage**: \n  - **DNS Management**: Full DNS record management (A, AAAA, CNAME, MX, TXT, NS, SRV)\n  - **Instance Management**: Create, manage, and control compute instances\n  - **SSH Keys**: Manage SSH keys for secure access\n  - **Backups**: Create and manage instance backups\n  - **Firewall**: Configure firewall groups and rules\n  - **Snapshots**: Create and manage instance snapshots\n  - **Regions**: Query region availability and capabilities\n  - **Reserved IPs**: Manage static IP addresses\n- **Smart Identifier Resolution**: Use human-readable names instead of UUIDs (e.g., \"web-server\" instead of UUID)\n- **Zone File Import/Export**: Standard zone file format support for bulk DNS operations\n- **Intelligent Validation**: Pre-creation validation with helpful suggestions\n- **CLI Interface**: Complete command-line tool for direct operations\n- **High-Level Client**: Convenient Python API for common operations\n- **Modern Development**: Fast development workflow with uv support\n\n## Smart Identifier Resolution\n\nOne of the key features is **automatic UUID lookup** across all services. Instead of requiring UUIDs, you can use human-readable identifiers:\n\n- **Instances**: Use label or hostname instead of UUID\n- **SSH Keys**: Use key name instead of UUID  \n- **Firewall Groups**: Use description instead of UUID\n- **Snapshots**: Use description instead of UUID\n- **Reserved IPs**: Use IP address instead of UUID\n\n### Examples\n\n```bash\n# Traditional approach (with UUIDs)\nmcp-vultr instances stop cb676a46-66fd-4dfb-b839-443f2e6c0b60\nmcp-vultr firewall rules list 5f2a4b6c-7b8d-4e9f-a1b2-3c4d5e6f7a8b\n\n# Smart approach (with names)\nmcp-vultr instances stop web-server\nmcp-vultr firewall rules list production-servers\n```\n\nThe system uses **exact matching** to ensure safety - if multiple resources have similar names, you'll get an error rather than operating on the wrong resource.\n\n## Quick Start\n\n### Installation\n\n```bash\n# Using uv (recommended - fast and modern)\nuv add mcp-vultr\n\n# Or using pip\npip install mcp-vultr\n```\n\n### Basic Usage\n\n```bash\n# Set your Vultr API key\nexport VULTR_API_KEY=\"your-api-key\"\n\n# DNS Management\nmcp-vultr domains list\nmcp-vultr records list example.com\nmcp-vultr setup-website example.com 192.168.1.100\n\n# Instance Management (with smart name resolution)\nmcp-vultr instances list\nmcp-vultr instances get web-server  # Uses name instead of UUID\nmcp-vultr instances stop web-server\n\n# SSH Key Management\nmcp-vultr ssh-keys list\nmcp-vultr ssh-keys add \"laptop\" \"ssh-rsa AAAAB3...\"\n\n# Firewall Management\nmcp-vultr firewall groups list\nmcp-vultr firewall rules list web-servers  # Uses description instead of UUID\n\n# Run as MCP server\nvultr-mcp-server\n```\n\n### Python API\n\n```python\nimport asyncio\nfrom mcp_vultr import VultrDNSClient, VultrDNSServer\n\nasync def main():\n    # DNS-specific client\n    dns_client = VultrDNSClient(\"your-api-key\")\n    \n    # List domains\n    domains = await dns_client.domains()\n    \n    # Add DNS records\n    await dns_client.add_a_record(\"example.com\", \"www\", \"192.168.1.100\")\n    await dns_client.add_mx_record(\"example.com\", \"@\", \"mail.example.com\", 10)\n    \n    # Get domain summary\n    summary = await dns_client.get_domain_summary(\"example.com\")\n    print(f\"Domain has {summary['total_records']} records\")\n    \n    # Full API client for all services\n    vultr = VultrDNSServer(\"your-api-key\")\n    \n    # Smart identifier resolution - use names instead of UUIDs!\n    instance = await vultr.get_instance(\"web-server\")  # By label\n    ssh_key = await vultr.get_ssh_key(\"laptop-key\")   # By name\n    firewall = await vultr.get_firewall_group(\"production\")  # By description\n    snapshot = await vultr.get_snapshot(\"backup-2024-01\")    # By description\n    reserved_ip = await vultr.get_reserved_ip(\"192.168.1.100\")  # By IP\n\nasyncio.run(main())\n```\n\n### MCP Integration\n\nThis package provides a complete MCP server that can be integrated with MCP-compatible clients:\n\n```python\nfrom mcp_vultr import create_mcp_server, run_server\n\n# Create server\nserver = create_mcp_server(\"your-api-key\")\n\n# Run server\nawait run_server(\"your-api-key\")\n```\n\n## Development\n\n### Prerequisites\n\n- Python 3.10+\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n- Vultr API key\n\n### Setup with uv (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/rsp2k/mcp-vultr.git\ncd mcp-vultr\n\n# Install dependencies\nuv sync --extra dev\n\n# Run tests\nuv run pytest\n\n# Run comprehensive test suite\nuv run python run_tests.py --all-checks\n\n# Format code\nuv run black src tests\nuv run isort src tests\n\n# Type checking\nuv run mypy src\n```\n\n### Setup with pip (Traditional)\n\n```bash\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Run comprehensive test suite\npython run_tests.py --all-checks\n```\n\n## MCP Tools Available\n\nThe MCP server provides 70+ tools across 8 service modules. All tools support **smart identifier resolution** - you can use human-readable names instead of UUIDs!\n\n### DNS Management (12 tools)\n- `dns_list_domains` - List all DNS domains\n- `dns_get_domain` - Get domain details\n- `dns_create_domain` - Create new domain\n- `dns_delete_domain` - Delete domain and all records\n- `dns_list_records` - List records for a domain\n- `dns_create_record` - Create new DNS record\n- `dns_update_record` - Update existing record\n- `dns_delete_record` - Delete DNS record\n- `dns_validate_record` - Validate record before creation\n- `dns_analyze_records` - Analyze domain configuration\n- `dns_import_zone_file` - Import DNS records from zone file\n- `dns_export_zone_file` - Export DNS records to zone file\n\n### Instance Management (9 tools)\n- `instances_list` - List all instances\n- `instances_get` - Get instance details (**smart**: by label, hostname, or UUID)\n- `instances_create` - Create new instance\n- `instances_update` - Update instance configuration\n- `instances_delete` - Delete instance (**smart**: by label, hostname, or UUID)\n- `instances_start` - Start a stopped instance (**smart**: by label, hostname, or UUID)\n- `instances_stop` - Stop a running instance (**smart**: by label, hostname, or UUID)\n- `instances_reboot` - Reboot instance (**smart**: by label, hostname, or UUID)\n- `instances_reinstall` - Reinstall instance OS (**smart**: by label, hostname, or UUID)\n\n### SSH Key Management (5 tools)\n- `ssh_keys_list` - List all SSH keys\n- `ssh_keys_get` - Get SSH key details (**smart**: by name or UUID)\n- `ssh_keys_create` - Add new SSH key\n- `ssh_keys_update` - Update SSH key (**smart**: by name or UUID)\n- `ssh_keys_delete` - Remove SSH key (**smart**: by name or UUID)\n\n### Backup Management (2 tools)\n- `backups_list` - List all backups\n- `backups_get` - Get backup details\n\n### Firewall Management (10 tools)\n- `firewall_list_groups` - List firewall groups\n- `firewall_get_group` - Get group details (**smart**: by description or UUID)\n- `firewall_create_group` - Create firewall group\n- `firewall_update_group` - Update group description (**smart**: by description or UUID)\n- `firewall_delete_group` - Delete firewall group (**smart**: by description or UUID)\n- `firewall_list_rules` - List rules in a group (**smart**: by description or UUID)\n- `firewall_get_rule` - Get specific rule (**smart**: group by description or UUID)\n- `firewall_create_rule` - Add firewall rule (**smart**: group by description or UUID)\n- `firewall_delete_rule` - Remove firewall rule (**smart**: group by description or UUID)\n- `firewall_setup_web_server_rules` - Quick setup for web servers (**smart**: group by description or UUID)\n\n### Snapshot Management (6 tools)\n- `snapshots_list` - List all snapshots\n- `snapshots_get` - Get snapshot details (**smart**: by description or UUID)\n- `snapshots_create` - Create instance snapshot\n- `snapshots_create_from_url` - Create snapshot from URL\n- `snapshots_update` - Update snapshot description (**smart**: by description or UUID)\n- `snapshots_delete` - Delete snapshot (**smart**: by description or UUID)\n\n### Region Information (4 tools)\n- `regions_list` - List all available regions\n- `regions_get_availability` - Check plan availability in region\n- `regions_find_regions_with_plan` - Find regions for specific plan\n- `regions_list_by_continent` - Filter regions by continent\n\n### Reserved IP Management (12 tools)\n- `reserved_ips_list` - List all reserved IPs\n- `reserved_ips_get` - Get reserved IP details (**smart**: by IP address or UUID)\n- `reserved_ips_create` - Reserve new IP address\n- `reserved_ips_update` - Update reserved IP label (**smart**: by IP address or UUID)\n- `reserved_ips_delete` - Release reserved IP (**smart**: by IP address or UUID)\n- `reserved_ips_attach` - Attach IP to instance (**smart**: by IP address or UUID)\n- `reserved_ips_detach` - Detach IP from instance (**smart**: by IP address or UUID)\n- `reserved_ips_convert_instance_ip` - Convert instance IP to reserved\n- `reserved_ips_list_by_region` - List IPs in specific region\n- `reserved_ips_list_unattached` - List unattached IPs\n- `reserved_ips_list_attached` - List attached IPs with instance info\n\n## CLI Commands\n\n```bash\n# Domain management\nmcp-vultr domains list\nmcp-vultr domains info example.com\nmcp-vultr domains create newdomain.com 192.168.1.100\n\n# Record management\nmcp-vultr records list example.com\nmcp-vultr records add example.com A www 192.168.1.100\nmcp-vultr records delete example.com record-id\n\n# Zone file operations\nmcp-vultr zones export example.com > example.zone\nmcp-vultr zones import example.com example.zone\n\n# Instance management (with smart identifier resolution)\nmcp-vultr instances list\nmcp-vultr instances create --region ewr --plan vc2-1c-1gb --os 387 --label web-server\nmcp-vultr instances get web-server            # By label\nmcp-vultr instances stop production.local     # By hostname\nmcp-vultr instances reboot web-server        # By label\n\n# SSH key management (with smart identifier resolution)\nmcp-vultr ssh-keys list\nmcp-vultr ssh-keys add laptop-key \"ssh-rsa AAAAB3...\"\nmcp-vultr ssh-keys delete laptop-key         # By name\n\n# Firewall management (with smart identifier resolution)\nmcp-vultr firewall groups list\nmcp-vultr firewall groups create \"web-servers\"\nmcp-vultr firewall rules list web-servers    # By description\nmcp-vultr firewall rules add web-servers --port 443 --protocol tcp\n\n# Snapshot management (with smart identifier resolution)\nmcp-vultr snapshots list\nmcp-vultr snapshots create instance-id --description \"backup-2024-01\"\nmcp-vultr snapshots delete backup-2024-01    # By description\n\n# Reserved IP management (with smart identifier resolution)\nmcp-vultr reserved-ips list\nmcp-vultr reserved-ips create --region ewr --type v4 --label production-ip\nmcp-vultr reserved-ips attach 192.168.1.100 instance-id  # By IP\nmcp-vultr reserved-ips delete 192.168.1.100             # By IP\n\n# Setup utilities\nmcp-vultr setup-website example.com 192.168.1.100\nmcp-vultr setup-email example.com mail.example.com\n\n# Start MCP server\nvultr-mcp-server\n```\n\n## Testing\n\nThis project follows FastMCP testing best practices with comprehensive test coverage:\n\n```bash\n# Run all tests (uv)\nuv run pytest\n\n# Run specific test categories\nuv run pytest -m unit          # Unit tests\nuv run pytest -m integration   # Integration tests  \nuv run pytest -m mcp          # MCP-specific tests\n\n# With coverage\nuv run pytest --cov=mcp_vultr --cov-report=html\n\n# Full validation suite\nuv run python run_tests.py --all-checks\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run the test suite (`uv run python run_tests.py --all-checks`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## Error Handling\n\nThe package provides specific exception types for better error handling:\n\n```python\nfrom mcp_vultr import (\n    VultrAPIError,\n    VultrAuthError,\n    VultrRateLimitError,\n    VultrResourceNotFoundError,\n    VultrValidationError\n)\n\ntry:\n    await client.get_domain(\"example.com\")\nexcept VultrAuthError:\n    print(\"Invalid API key or insufficient permissions\")\nexcept VultrResourceNotFoundError:\n    print(\"Domain not found\")\nexcept VultrRateLimitError:\n    print(\"Rate limit exceeded, please try again later\")\nexcept VultrAPIError as e:\n    print(f\"API error {e.status_code}: {e.message}\")\n```\n\n## Configuration\n\nSet your Vultr API key via environment variable:\n\n```bash\nexport VULTR_API_KEY=\"your-vultr-api-key\"\n```\n\nOr pass directly to the client:\n\n```python\nclient = VultrDNSClient(\"your-api-key\")\nserver = create_mcp_server(\"your-api-key\")\n```\n\n## Changelog\n\n### v1.9.0 (Latest)\n- **Feature**: Universal UUID lookup pattern across all modules - use human-readable names everywhere!\n  - Instances: lookup by label or hostname\n  - SSH Keys: lookup by name\n  - Firewall Groups: lookup by description\n  - Snapshots: lookup by description\n  - Reserved IPs: lookup by IP address\n- **Feature**: All UUID lookups use exact matching for safety\n- **Enhancement**: Improved error messages when resources not found\n\n### v1.8.1\n- **Feature**: Smart identifier resolution for Reserved IPs\n- **Fix**: Reserved IP tools now accept IP addresses directly\n\n### v1.8.0\n- **Feature**: Complete Reserved IP management (12 new tools)\n- **Feature**: Support for IPv4 and IPv6 reserved IPs\n- **Feature**: Convert existing instance IPs to reserved\n\n### v1.1.0\n- **Feature**: Zone file import/export functionality\n- **Feature**: Standard DNS zone file format support\n\n### v1.0.1\n- **Major**: Migrated to FastMCP 2.0 framework\n- **Feature**: Custom exception hierarchy for better error handling\n- **Feature**: Enhanced IPv6 validation with ipaddress module\n- **Feature**: HTTP request timeouts (30s total, 10s connect)\n- **Feature**: Full uv package manager integration\n- **Fix**: Resolved event loop issues with FastMCP\n\n### v1.0.0\n- Initial release with complete MCP server implementation\n- Support for DNS, Instances, SSH Keys, Backups, Firewall, Snapshots, Regions\n- CLI interface and Python client library\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [GitHub Repository](https://github.com/rsp2k/mcp-vultr)\n- [PyPI Package](https://pypi.org/project/mcp-vultr/)\n- [Vultr API Documentation](https://www.vultr.com/api/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [uv Package Manager](https://docs.astral.sh/uv/)\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A comprehensive Model Context Protocol (MCP) server for managing Vultr DNS records",
    "version": "1.9.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/rsp2k/mcp-vultr/issues",
        "Changelog": "https://github.com/rsp2k/mcp-vultr/blob/main/CHANGELOG.md",
        "Documentation": "https://mcp-vultr.readthedocs.io/",
        "Homepage": "https://github.com/rsp2k/mcp-vultr",
        "Repository": "https://github.com/rsp2k/mcp-vultr.git"
    },
    "split_keywords": [
        "vultr",
        " dns",
        " mcp",
        " model-context-protocol",
        " dns-management",
        " api",
        " mcp-server"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c56aabc69cccf8b02e6fe2df84099226734b91ee5fb138fea95fe1eb1a8a437c",
                "md5": "420fc5989f13219dde6b45df45315005",
                "sha256": "37b545b407734363a9e3562cabe2d023ee8a2f58efa092f59357ee663bc7fde1"
            },
            "downloads": -1,
            "filename": "mcp_vultr-1.9.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "420fc5989f13219dde6b45df45315005",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 38899,
            "upload_time": "2025-08-06T00:39:18",
            "upload_time_iso_8601": "2025-08-06T00:39:18.778396Z",
            "url": "https://files.pythonhosted.org/packages/c5/6a/abc69cccf8b02e6fe2df84099226734b91ee5fb138fea95fe1eb1a8a437c/mcp_vultr-1.9.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "87825f39368f347c653da48626f10ec256b1d67cee3bb966bd35864cbcc35e08",
                "md5": "fb4fc26ee9ded82a1b825ede9e2eaa7f",
                "sha256": "1a5922334e74b07e56a709bc2c8914dfdf048117157bd861571a549f27d92103"
            },
            "downloads": -1,
            "filename": "mcp_vultr-1.9.0.tar.gz",
            "has_sig": false,
            "md5_digest": "fb4fc26ee9ded82a1b825ede9e2eaa7f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 50767,
            "upload_time": "2025-08-06T00:39:22",
            "upload_time_iso_8601": "2025-08-06T00:39:22.162330Z",
            "url": "https://files.pythonhosted.org/packages/87/82/5f39368f347c653da48626f10ec256b1d67cee3bb966bd35864cbcc35e08/mcp_vultr-1.9.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-06 00:39:22",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "rsp2k",
    "github_project": "mcp-vultr",
    "github_not_found": true,
    "lcname": "mcp-vultr"
}