configuration

Configuration

1. Project Installation and Setup

Before using the MCP server, you need to install the necessary software and set up the project on your local machine.

Prerequisites

Ensure you have the following software installed:

• Python 3.10+
• UV (Python package manager)
• A running OpenNebula deployment that is accessible from your machine.
• An MCP Client (e.g., Cursor, Warp Terminal, MCP Host).

Installation Steps

1. Install UV (if you haven't already):

   # On Linux/macOS
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Or via pip
   pip install uv

2. Clone the Repository:

   git clone https://github.com/OpenNebula/one-mcp.git
   cd one-mcp

3. Create a Virtual Environment and Install Dependencies:

   # Create the virtual environment
   uv venv
   
   # Activate the environment
   source .venv/bin/activate
   
   # Install project dependencies
   uv sync

4. Verify the Installation: Run the server to confirm it starts correctly.

   python main.py

   You should see the output: >>> Starting MCP server...

2. MCP Client Configuration

Integrate the MCP server with your AI-powered client for seamless interaction.

MCPHost CLI

mcphost is an open-source, command-line host application for the Model Context Protocol. It enables Large Language Models (LLMs) — including proprietary models from providers like Anthropic and open-source models via Ollama — to interact with external tools. This allows you to use the OpenNebula MCP Server directly from your terminal for powerful scripting and automation.

1. Configure MCPHost: Create a configuration file at ~/.mcphost.yml and add the opennebula-mcp-server as a local server.

   # ~/.mcphost.yml
   
   # Add the OpenNebula server to your list of MCP servers
   mcpServers:
     opennebula-mcp-server:
       type: "local"
       command: ["uv", "run", "-p", "/MY_PATH/one-mcp/.venv/bin/python", "--", "/MY_PATH/one-mcp/main.py"]
       cwd: "/MY_PATH/one-mcp"
       
   # (Optional) Configure your preferred model and other settings
   model: "anthropic:claude-sonnet-4-20250514"

2. Usage and Verification: To verify that mcphost has successfully connected to the OpenNebula MCP Server:

   1. Start mcphost in interactive mode:

      mcphost

   2. Inside the interactive session, run the /servers command:

      /servers
      

   3. You should see opennebula-mcp-server listed as an available server. This confirms the connection is active, and you can now ask the LLM to perform tasks:

      > List all my OpenNebula clusters
      

3. Usage Example: Once configured, you can interact with your OpenNebula environment directly from the command line.

   # Run in non-interactive mode with a specific prompt
   mcphost -p "List all my OpenNebula clusters"
   
   # Run in interactive mode to have a chat session
   mcphost
   
   # Quiet mode - only output the AI response (no UI elements)
   mcphost -p "List running VMs" --quiet

Cursor IDE

1. Configure MCP Server in Cursor: Open your Cursor MCP settings file (~/.cursor/mcp.json) and add the following server configuration. Remember to update the paths to match your project's location.

   {
     "mcpServers": {
       "opennebula-mcp-server": {
         "command": "uv",
         "args": [
           "run",
           "-p",
           "/MY_PATH/one-mcp/.venv/bin/python",
           "--",
           "/MY_PATH/one-mcp/main.py"
         ],
         "type": "command",
         "cwd": "/MY_PATH/one-mcp"
       }
     }
   }

Warp Terminal

1. Configure MCP Server in Warp: In Warp's settings (Settings > AI > MCP Server), add the following configuration. Remember to adjust the paths.

   {
     "opennebula-mcp-server": {
       "command": "uv",
       "args": [
         "run",
         "-p",
         "/MY_PATH/one-mcp/.venv/bin/python",
         "--",
         "/MY_PATH/one-mcp/main.py"
       ],
       "env": {},
       "working_directory": null,
       "start_on_launch": true
     }
   }

3. Server Configuration

The OpenNebula MCP Server can be configured at runtime using command-line arguments passed within the MCP Server's configuration file. These arguments allow you to control features like write access and logging.

The following arguments are available:

• --allow-write / --no-allow-write: Enables or disables "write mode," which grants the AI permission to execute mutating operations such as creating, managing, or deleting VM resources. By default, this is disabled to run the server in a safe, read-only mode.
• --log-level [LEVEL]: Sets the logging verbosity. LEVEL can be one of DEBUG, INFO, WARNING, ERROR, or CRITICAL. The default is INFO.
• --log-file / --no-log-file: Enables or disables logging to a file in the log/ directory. File logging is enabled by default.

How to Apply Arguments

You can add these arguments to the command or args array in your MCP client's configuration.

MCPHost Example (~/.mcphost.yml)

To enable write mode and set the log level to DEBUG:

# ~/.mcphost.yml
mcpServers:
  opennebula-mcp-server:
    type: "local"
    command: [
      "uv", "run", "-p", "/MY_PATH/one-mcp/.venv/bin/python", "--",
      "/MY_PATH/one-mcp/main.py",
      "--allow-write", # 👈
      "--log-level", "DEBUG" # 👈
    ]
    cwd: "/MY_PATH/one-mcp"

4. Testing Environment Configuration

Configure your environment to run the project's test suites.

Promptfoo (AI Interaction Tests)

Promptfoo is used to test the MCP Server's ability to select and use the correct tools.

⚠️ Important: Use promptfoo version 0.117.4 for compatibility with the test suite:

npx promptfoo@0.117.4 eval -c promptfooconfig.yaml

1. Set Up Environment Variables: Create an .env file in the project's root directory.

2. Add Your OpenAI API Key: Add your API key to the .env file. This is required for the evaluation model.

   OPENAI_API_KEY=sk-proj-XXX
   

Pytest (Tool Unit Tests)

Pytest is used to run unit tests against individual tool functions.

1. Configure Test VM IP Address: The VM-related tests require an active OpenNebula VM. Edit src/tests/pytest/conftest.py and set TEST_VM_IP_ADDRESS to the IP of your test VM.

   # src/tests/pytest/conftest.py
   
   # ...
   # Update this IP address to match an active VM with SSH access
   TEST_VM_IP_ADDRESS = "172.20.0.12"  # 👈 Replace with your test VM's IP

2. Test VM Requirements: Your test VM must meet the following criteria:

   • State must be ACTIVE/RUNNING.
   • SSH access must be enabled.
   • The VM must have root access or sudo privileges.
   • The MCP server host must have network connectivity to the VM.

3. Verify VM Connectivity: You can test the connection from your terminal:

   # Replace with your test VM's IP
   ssh root@172.20.0.12 "echo 'VM connectivity test successful'"