Initial commit: Vultr MCP Server
This commit is contained in:
275
README.md
Normal file
275
README.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user