Skip to content

runitsolutions/mcp-server-ovh

BranchesTags

Repository files navigation

MCP Server OVH

License: MIT TypeScript Node.js CI npm version

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 (17/17 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 ✅

❌ 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
  • 🛠️ 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": {}
}

🛠️ 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:

📋 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

Related Projects

🔧 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

📄 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

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

Release v1.1.1 Latest
Aug 30, 2025
+ 2 releases

Packages

No packages published

Languages