Getting Started

This guide covers installation and basic configuration of unblu-mcp.

Installation

This package is available on PyPI. The recommended installation method is via uv tool install:

uv tool install unblu-mcp

This installs the unblu-mcp command to ~/.local/bin/ and avoids cache locking issues that affect long-running MCP servers when using uvx.

Note

You can also run directly via uvx unblu-mcp without installation, but this will block uv cache prune operations while the server is running.

From source

git clone https://github.com/detailobsessed/unblu-mcp.git
cd unblu-mcp
uv sync

MCP Client Configuration

Add the server to your MCP client configuration (Claude Desktop, Windsurf, etc.):

With Kubernetes Provider

The K8s provider automatically manages kubectl port-forward connections to your Unblu deployment. This is the most tested configuration.

macOSWindows

~/Library/Application Support/Claude/claude_desktop_config.json or IDE MCP config:

{
  "mcpServers": {
    "unblu": {
      "command": "unblu-mcp",
      "args": ["--provider", "k8s", "--environment", "dev"],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "unblu": {
      "command": "unblu-mcp",
      "args": ["--provider", "k8s", "--environment", "dev"],
      "env": {
        "PATH": "C:\\Users\\YOUR_USERNAME\\.local\\bin;C:\\Program Files\\...;..."
      }
    }
  }
}

See Kubernetes Provider for setting up your environments.

With Environment Variables

For direct API access without Kubernetes:

{
  "mcpServers": {
    "unblu": {
      "command": "unblu-mcp",
      "args": [],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "UNBLU_BASE_URL": "https://your-instance.unblu.cloud/app/rest/v4",
        "UNBLU_API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
UNBLU_BASE_URL	No	Your Unblu API base URL (default: https://unblu.cloud/app/rest/v4)
UNBLU_API_KEY	One of these	API key for authentication (Bearer token)
UNBLU_USERNAME	One of these	Username for basic authentication
UNBLU_PASSWORD	With username	Password for basic authentication

Command Line Usage

# Run with stdio transport (default, for MCP clients)
unblu-mcp

# Use a custom swagger.json location
unblu-mcp --spec /path/to/swagger.json

# Run with Eunomia authorization policy (requires unblu-mcp[safety])
unblu-mcp --policy /path/to/mcp_policies.json

# Run with K8s provider (auto-starts kubectl port-forward)
unblu-mcp --provider k8s --environment dev

# Run with K8s provider using custom config file
unblu-mcp --provider k8s --environment my-env --k8s-config /path/to/k8s_environments.yaml

# Show version
unblu-mcp --version

# Show debug info
unblu-mcp --debug-info

CLI Arguments

Argument	Values	Default	Description
--spec	path	auto-detect	Path to swagger.json
--policy	path	none	Eunomia policy file
--provider	default, k8s	default	Connection provider
--environment	string	dev	K8s environment (with --provider k8s)
--k8s-config	path	none	Custom K8s environments YAML file

Feedback