MCP Server OVH

A Model Context Protocol (MCP) server that provides standardized access to OVH API services. This server enables AI assistants and applications to interact with OVH's cloud infrastructure through a unified, secure interface.

👨‍💻 Author & Company

Author: Isaac Campos Mesén Company: RunIT Solutions Repository: GitHub - runitsolutions/mcp-server-ovh

✅ Project Status

Status: 🟢 FULLY OPERATIONAL & TESTED

• ✅ Build: TypeScript compilation successful
• ✅ Runtime: Server starts without errors
• ✅ Schema Validation: Input validation working correctly
• ✅ MCP Integration: Compatible with MCP clients
• ✅ CommonJS: Uses require() for module loading
• ✅ TypeScript: Full type safety with proper declarations
• ✅ API Endpoints Verified: All endpoints tested against OVH Console
• ✅ Documentation Updated: README reflects verified endpoints

🔍 Endpoints Verification Results

Last Verified: $(date) OVH Console: https://eu.api.ovh.com/console/

✅ WORKING ENDPOINTS (27/27 tested - 100% SUCCESS):

• /me - User information ✅
• /me/bill - Billing information ✅
• /me/payment/method - Payment methods ✅
• /service - Services list ✅
• /services - Services list (plural) ✅
• /dedicated/server - Dedicated servers ✅
• /vps - VPS instances ✅
• /me/order - Orders ✅
• /me/api/application - API applications ✅
• /cloud/project - Cloud projects ✅
• /ip - IP addresses ✅
• /ipLoadbalancing - Load balancers ✅
• /dedicatedCloud - Dedicated Cloud ✅
• /metrics - Metrics ✅
• /license/windows - Windows licenses ✅
• /dbaas/logs - DBaaS Logs ✅
• /ssl - SSL certificates ✅
• /vrack - vRack ✅
• /veeamCloudConnect - Veeam Cloud Connect ✅
• /nutanix - Nutanix ✅

DNS Management (NEW):

• /domain/zone - List DNS zones ✅
• /domain/zone/{zone} - Zone details ✅
• /domain/zone/{zone}/record - List/Create records ✅
• /domain/zone/{zone}/record/{id} - Get/Update/Delete record ✅
• /domain/zone/{zone}/refresh - Apply DNS changes ✅
• /domain/zone/{zone}/status - Zone status ✅
• /domain/zone/{zone}/export - Export zone (BIND format) ✅

❌ ENDPOINTS REQUIRING PERMISSIONS:

• /me/services - Requires specific API permissions
• /domain - Requires domain management permissions
• /me/api/logs - Requires audit log permissions
• /hosting/web - Requires web hosting permissions
• /email/domain - Requires email permissions
• /sms - Requires SMS permissions

Features

• 🔐 Secure Authentication: Support for both API key and OAuth2 authentication methods
• 🌐 DNS Management: Complete DNS zone and record management (create, read, update, delete)
• 🛠️ Standardized Tools: Clean MCP tool interfaces for common OVH operations
• ✅ Input Validation: Robust validation using Zod schemas
• 🚀 Modern API: Built with the latest MCP SDK following best practices
• 📝 TypeScript: Full TypeScript support with strict type checking
• 🧪 Well Tested: Comprehensive test suite with Jest
• 📚 Well Documented: Complete documentation and examples

Installation

Prerequisites

• Node.js 18.x or higher
• npm or yarn
• OVH API credentials (see Setup section)

Install from npm

npm install mcp-server-ovh

Build from source

git clone https://github.com/runitsolutions/mcp-server-ovh.git
cd mcp-server-ovh
npm install
npm run build

Setup

OVH API Credentials

You need to obtain API credentials from OVH. There are two authentication methods:

Method 1: API Keys (Recommended)

1. Go to OVH Manager
2. Navigate to API Keys section
3. Create a new application key
4. Note down your App Key, App Secret, and Consumer Key

Method 2: OAuth2

1. Register your application in OVH's OAuth2 system
2. Obtain your Client ID and Client Secret

Configuration

Create a .env file in your project root:

# For API Key authentication
OVH_ENDPOINT=ovh-eu
OVH_APP_KEY=your_app_key_here
OVH_APP_SECRET=your_app_secret_here
OVH_CONSUMER_KEY=your_consumer_key_here

# For OAuth2 authentication (alternative)
OVH_CLIENT_ID=your_client_id_here
OVH_CLIENT_SECRET=your_client_secret_here

Usage

As an MCP Server

The server communicates via stdio and can be used with any MCP-compatible client.

Direct execution

npm start

Using with MCP clients

The server is designed to work with MCP-compatible clients like Claude Desktop or other AI assistants that support the Model Context Protocol.

Available Tools

1. Initialize OVH Client

Initialize the OVH API client with your credentials.

{
  "name": "ovh_initialize_client",
  "arguments": {
    "endpoint": "ovh-eu",
    "appKey": "your_app_key",
    "appSecret": "your_app_secret",
    "consumerKey": "your_consumer_key"
  }
}

2. Initialize OAuth2 Client

Initialize with OAuth2 credentials.

{
  "name": "ovh_oauth2_initialize",
  "arguments": {
    "endpoint": "ovh-eu",
    "clientID": "your_client_id",
    "clientSecret": "your_client_secret"
  }
}

3. Make API Request

Make a custom request to any OVH API endpoint.

{
  "name": "ovh_request",
  "arguments": {
    "method": "GET",
    "path": "/me",
    "data": {} // Optional data for POST/PUT requests
  }
}

4. Get User Information

Get information about the authenticated user.

{
  "name": "ovh_get_user_info",
  "arguments": {}
}

5. Get User Bills

Retrieve billing information.

{
  "name": "ovh_get_bills",
  "arguments": {}
}

6. Get User Services

List all services associated with the account.

{
  "name": "ovh_get_services",
  "arguments": {}
}

7. Get Payment Methods

Retrieve available payment methods for the account.

{
  "name": "ovh_get_payment_methods",
  "arguments": {}
}

8. Get Orders

List all orders placed with OVH.

{
  "name": "ovh_get_orders",
  "arguments": {}
}

9. Get Cloud Projects

List all cloud projects associated with the account.

{
  "name": "ovh_get_cloud_projects",
  "arguments": {}
}

10. Get Dedicated Servers

List all dedicated servers in the account.

{
  "name": "ovh_get_dedicated_servers",
  "arguments": {}
}

11. Get VPS Instances

List all VPS instances in the account.

{
  "name": "ovh_get_vps",
  "arguments": {}
}

12. Get IP Addresses

List all IP addresses associated with the account.

{
  "name": "ovh_get_ips",
  "arguments": {}
}

13. Get vRack Information

Get vRack network information.

{
  "name": "ovh_get_vrack",
  "arguments": {}
}

14. Get Load Balancers

List all load balancers in the account.

{
  "name": "ovh_get_load_balancers",
  "arguments": {}
}

15. Get SSL Certificates

List all SSL certificates.

{
  "name": "ovh_get_ssl_certificates",
  "arguments": {}
}

16. Get DBaaS Logs Services

List all DBaaS Logs services.

{
  "name": "ovh_get_dbaas_logs",
  "arguments": {}
}

🌐 DNS Management Tools

These tools provide comprehensive DNS zone and record management.

17. Get DNS Zones (Domains)

List all DNS zones in your OVH account.

{
  "name": "ovh_get_domains",
  "arguments": {}
}

18. Get DNS Zone Details

Get detailed information about a specific DNS zone.

{
  "name": "ovh_get_domain_zone",
  "arguments": {
    "zone": "example.com"
  }
}

19. List DNS Records

List DNS records for a zone with optional filtering.

{
  "name": "ovh_get_dns_records",
  "arguments": {
    "zone": "example.com",
    "fieldType": "A",        // Optional: filter by type (A, AAAA, CNAME, MX, TXT, etc.)
    "subDomain": "www"       // Optional: filter by subdomain
  }
}

20. Get DNS Record Details

Get details of a specific DNS record by ID.

{
  "name": "ovh_get_dns_record",
  "arguments": {
    "zone": "example.com",
    "recordId": 123456789
  }
}

21. Create DNS Record

Create a new DNS record in a zone.

{
  "name": "ovh_create_dns_record",
  "arguments": {
    "zone": "example.com",
    "fieldType": "A",
    "subDomain": "www",      // Empty string for root domain
    "target": "192.168.1.1",
    "ttl": 3600              // Optional, default: 3600
  }
}

22. Update DNS Record

Update an existing DNS record.

{
  "name": "ovh_update_dns_record",
  "arguments": {
    "zone": "example.com",
    "recordId": 123456789,
    "target": "192.168.1.2", // Optional
    "ttl": 7200              // Optional
  }
}

23. Delete DNS Record

Delete a DNS record.

{
  "name": "ovh_delete_dns_record",
  "arguments": {
    "zone": "example.com",
    "recordId": 123456789
  }
}

24. Refresh DNS Zone

Apply pending DNS changes to a zone. Required after create/update/delete operations.

{
  "name": "ovh_refresh_dns_zone",
  "arguments": {
    "zone": "example.com"
  }
}

25. Get DNS Zone Status

Get the current status of a DNS zone (propagation status, errors).

{
  "name": "ovh_get_dns_zone_status",
  "arguments": {
    "zone": "example.com"
  }
}

26. Export DNS Zone

Export DNS zone in BIND format.

{
  "name": "ovh_export_dns_zone",
  "arguments": {
    "zone": "example.com"
  }
}

DNS Workflow Example

// 1. List your DNS zones
{ "name": "ovh_get_domains", "arguments": {} }

// 2. View records for a zone
{ "name": "ovh_get_dns_records", "arguments": { "zone": "example.com" } }

// 3. Create a new A record
{ "name": "ovh_create_dns_record", "arguments": {
    "zone": "example.com",
    "fieldType": "A",
    "subDomain": "api",
    "target": "1.2.3.4"
  }
}

// 4. IMPORTANT: Apply changes
{ "name": "ovh_refresh_dns_zone", "arguments": { "zone": "example.com" } }

// 5. Check propagation status
{ "name": "ovh_get_dns_zone_status", "arguments": { "zone": "example.com" } }

🛠️ IDE Integration

This MCP server can be integrated with various IDEs and editors that support the Model Context Protocol. Below are the instructions for popular IDEs.

Cursor Integration

Cursor supports MCP servers through the Model Context Protocol. You can add this OVH MCP server to your Cursor configuration.

Option 1: Project Configuration

Create a .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "ovh-api": {
      "command": "npx",
      "args": ["mcp-server-ovh"],
      "env": {
        "OVH_ENDPOINT": "ovh-eu",
        "OVH_APP_KEY": "your_app_key_here",
        "OVH_APP_SECRET": "your_app_secret_here",
        "OVH_CONSUMER_KEY": "your_consumer_key_here"
      }
    }
  }
}

Option 2: Global Configuration

Create a ~/.cursor/mcp.json file for system-wide access:

{
  "mcpServers": {
    "ovh-api": {
      "command": "npx",
      "args": ["mcp-server-ovh"],
      "env": {
        "OVH_ENDPOINT": "ovh-eu",
        "OVH_APP_KEY": "your_app_key_here",
        "OVH_APP_SECRET": "your_app_secret_here",
        "OVH_CONSUMER_KEY": "your_consumer_key_here"
      }
    }
  }
}

Other IDEs

VS Code with MCP Extension

If you're using VS Code with an MCP extension:

1. Install the MCP extension for VS Code
2. Configure the server in your MCP settings:

{
  "server": "ovh-api",
  "command": "npx",
  "args": ["mcp-server-ovh"],
  "env": {
    "OVH_ENDPOINT": "ovh-eu",
    "OVH_APP_KEY": "your_app_key_here",
    "OVH_APP_SECRET": "your_app_secret_here",
    "OVH_CONSUMER_KEY": "your_consumer_key_here"
  }
}

Other MCP-Compatible IDEs

For other IDEs that support MCP:

1. Ensure your IDE supports the Model Context Protocol
2. Configure the server using the command: npx mcp-server-ovh
3. Set the required environment variables for OVH authentication

Authentication Setup

Before using the MCP server, you need to set up OVH API credentials:

# Set environment variables
export OVH_ENDPOINT="ovh-eu"
export OVH_APP_KEY="your_app_key"
export OVH_APP_SECRET="your_app_secret"
export OVH_CONSUMER_KEY="your_consumer_key"

Or create a .env file in your project directory:

OVH_ENDPOINT=ovh-eu
OVH_APP_KEY=your_app_key_here
OVH_APP_SECRET=your_app_secret_here
OVH_CONSUMER_KEY=your_consumer_key_here

Usage in IDE

Once configured, you can use the OVH MCP server in your IDE by:

1. Asking for OVH information: "What services do I have in OVH?"
2. Checking account details: "Show my OVH account information"
3. Billing inquiries: "What are my recent OVH bills?"
4. Service management: "List all my OVH services"

The AI assistant will automatically use the available OVH tools when relevant to your questions.

Development

Project Structure

src/
├── index.ts              # Main server implementation
├── types/
│   └── ovh.d.ts         # OVH API type definitions
└── __tests__/           # Test files
    ├── server.test.ts   # Server functionality tests
    └── validation.test.ts # Input validation tests

Development Commands

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (watch mode)
npm run dev

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Run tests (organized by type)
npm test                    # All tests
npm run test:unit          # Unit tests
npm run test:integration   # Integration tests
npm run test:e2e           # End-to-end tests

# Specific tests
npm run test:endpoints     # Verify OVH endpoints
npm run test:server        # MCP server tests
npm run test:client        # MCP client tests
npm run test:full          # Complete integration tests

# Coverage and watch mode
npm run test:coverage      # Tests with coverage report
npm run test:watch         # Tests in watch mode

# Clean build artifacts
npm run clean

Testing Structure

The test suite is organized in 4 levels:

📁 tests/unit/ - Unit Tests

• Zod schema validation
• MCP server functions
• Error handling
• Response parsing

📁 tests/integration/ - Integration Tests

• OVH API connectivity
• Endpoint verification (17/17 ✅)
• Client-server communication
• Authentication

📁 tests/e2e/ - End-to-End Tests

• Complete initialization flow
• Full MCP communication
• Real tool calls
• Response handling

📁 tests/utils/ - Utilities

• Test configuration
• Common helpers
• Mock clients

Run Tests

# All organized tests
npm test                    # Complete suite
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests only
npm run test:e2e           # End-to-end tests only

# Tests by specific functionality
npm run test:endpoints     # Verify 17 OVH endpoints
npm run test:server        # Server functionality
npm run test:client        # MCP client
npm run test:full          # Complete integration

# With coverage and watch
npm run test:coverage      # Coverage report
npm run test:watch         # Watch mode

Code Quality

This project follows strict code quality standards:

• ESLint: Configured with TypeScript rules
• Prettier: Code formatting (can be added if needed)
• Jest: Comprehensive test suite
• TypeScript: Strict mode enabled
• Pre-commit hooks: Quality checks before commits

API Reference

Supported Endpoints

The server provides access to OVH's REST API endpoints through both dedicated tools and generic requests:

✅ Verified Working Endpoints:

• /me - User account information
• /me/bill - Billing information
• /me/payment/method - Payment methods
• /me/order - Order history
• /me/api/application - API applications
• /service - Service listings
• /services - Service listings (plural)
• /cloud/project - Cloud projects
• /dedicated/server - Dedicated servers
• /vps - VPS instances
• /ip - IP addresses
• /ipLoadbalancing - Load balancers
• /dedicatedCloud - Dedicated Cloud
• /metrics - Metrics services
• /license/windows - Windows licenses
• /dbaas/logs - DBaaS Logs services
• /ssl - SSL certificates
• /vrack - vRack network
• /veeamCloudConnect - Veeam Cloud Connect
• /nutanix - Nutanix services

🔧 Generic Endpoint Access:

• Any OVH API endpoint via the ovh_request tool
• Full OVH API compatibility through the console: https://eu.api.ovh.com/console/

📋 Endpoints Requiring Specific Permissions:

• /me/services - Requires additional API permissions
• /domain - Requires domain management permissions
• /hosting/web - Requires web hosting permissions
• /email/domain - Requires email permissions
• /sms - Requires SMS permissions

Error Handling

The server provides clear error messages for:

• Authentication failures
• Invalid input validation
• API rate limits
• Network connectivity issues
• Invalid API responses

Rate Limiting

Be aware of OVH API rate limits. The server includes error handling for rate limit scenarios but doesn't implement automatic retry logic.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR
• Use conventional commit messages

Security

• Never commit API credentials to version control
• Use environment variables for sensitive data
• The server validates all inputs to prevent injection attacks
• API keys are stored securely and not logged

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 OVH API Documentation
• 🐛 Report Issues
• 💬 Discussions

Related Projects

• Model Context Protocol - The protocol this server implements
• OVH API - OVH's official API documentation
• MCP SDK - The SDK used to build this server
• GitHub Repository - Source code and issues

🔧 Troubleshooting

Common Issues

Authentication Problems

• Error: "OVH client not initialized"
• Solution: Ensure all required environment variables are set
• Check: Verify your API credentials are correct and have proper permissions

Connection Issues

• Error: Network timeout or connection failed
• Solution: Check your internet connection and OVH endpoint configuration
• Check: Verify the OVH_ENDPOINT matches your account region

Permission Errors

• Error: API access denied
• Solution: Ensure your API keys have the necessary permissions
• Check: Review OVH Manager API key permissions

Debug Mode

Enable debug logging by setting the environment variable:

export DEBUG=mcp-server-ovh

Logs

View MCP server logs in your IDE:

1. Open the Output panel (usually Ctrl+Shift+U)
2. Select "MCP Logs" from the dropdown
3. Check for connection errors, authentication issues, or server crashes

📚 Examples

Basic Usage

// In your MCP-compatible IDE
// Ask: "What OVH services do I have?"
// The AI will automatically use the ovh_get_services tool

// Ask: "Show my OVH account information"
// The AI will use the ovh_get_user_info tool

// Ask: "What are my recent OVH bills?"
// The AI will use the ovh_get_bills tool

Advanced Integration

// Custom API calls
// Ask: "Make a custom API call to /me/service/domain.example.com"
// The AI will use the ovh_request tool with appropriate parameters

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📖 OVH API Documentation
• 🏢 RunIT Solutions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ by RunIT Solutions using the Model Context Protocol