MLRun MCP Server

Overview

The MLRun MCP (Model Context Protocol) Server provides seamless integration between MLRun and MCP-compatible clients. This server exposes MLRun functionality as MCP tools, allowing you to interact with MLRun projects, runs, model endpoints, and other components through any MCP-enabled client.

Installation

Prerequisites

• Python 3.11 or higher
• Cursor or any IDE supporting custom local / remote MCP servers
• Valid MLRun credentials (V3IO access key if using Iguazio platform)

Install with Cursor

Open Settings -> Open MCP Settings -> MCP -> New MCP Server and paste below

Cursor Local MCP Server

"mlrun-local-mcp": {
   "command": "npx",
   "args": [
      "-y",
      "mcp-remote",
      "http://127.0.0.1:8110/mcp",
      "--allow-http"
   ]
}

Cursor Local MCP Server with Authentication

NOTE: When running against an Iguazio system, replace AUTH_TOKEN value with an access token.

{
  "mlrun-local-mcp-auth": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8110/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "<MY_ACCESS_TOKEN>"
      }
  }
}

Troubleshooting

1. SSL Certificate Errors: Set API_SSL_VERIFY=false for self-signed certificates
2. Authentication Failures: Verify your AUTH_TOKEN and API_AUTH_MODE are configure correctly
3. Connection Timeouts: Ensure your API_BASE_URL is accessible within your network

Contributing

Development Setup

1. Prerequisites

   • Python 3.11+
   • uv for dependency management

2. Clone and Install

   git clone <repository-url>
   cd mcp-server
   uv sync

3. Environment Configuration

   cp .env.template .env
   # Edit .env with your MLRun API settings:
   # API_BASE_URL=https://your-mlrun-api.com
   # API_SSL_VERIFY=true
   # API_AUTH_MODE=igz3  # or "none" for no auth
   # API_ACTIVE_PROJECT=default

Running the Server

Stdio Mode (for testing):

uv run mlrun-mcp-server

HTTP Mode (for MCP clients):

uv run mlrun-mcp-server --http

Project Structure

src/mcp_server/
├── __init__.py             # Package initialization
├── server.py               # Main MCP server and tools
├── cli.py                  # Command-line interface
├── config.py               # Configuration management
├── auth_providers/         # Authentication providers
│   └── iguazio.py          # Iguazio auth implementation
└── mlrun_client/           # MLRun API integration
    ├── __init__.py
    └── api_client.py       # Async MLRun client wrapper

Adding New Tools

1. Define the tool in src/mcp_server/server.py:

   @mcp.tool(title="Your tool name")
   async def your_tool_function(param: str) -> str:
       """Tool description."""
       async with get_mlrun_api_client() as client:
           return await client.your_method(param)

2. Implement the API method in src/mcp_server/mlrun_client/api_client.py:

   async def your_method(self, *args, **kwargs) -> str:
       """Your method implementation."""
       return await asyncio.to_thread(self._client.your_mlrun_call, *args, **kwargs)

Code Standards

• Linting: Uses Ruff for code formatting and linting
• Type Hints: Full type annotations required
• Async/Await: Use async patterns for all I/O operations
• Documentation: Docstrings for all public functions

Testing

# Run linter
uvx ruff check src/ --select I --fix
uvx ruff format src/

The MCP Inspector is a very useful tool for developers working with Model Context Protocol servers as it provides interactive testings, real-time debugging and eases the development workflow.

# Use STDIO transport
npx @modelcontextprotocol/inspector uv run mlrun-mcp-server