Skip to content
Xplorr Docs

Self-Host MCP Server with Docker: Container Deployment Guide

import { Steps } from ‘@astrojs/starlight/components’;

Self-Host MCP Server with Docker

Section titled “Self-Host MCP Server with Docker”

Run the Xplorr MCP server as a Docker container on your own infrastructure. The image is published to GitHub Container Registry and works on any platform that runs Docker (Linux, macOS, Windows).

When to Self-Host

Section titled “When to Self-Host”

Use Docker self-hosting when:

  • You need the MCP server inside a private network or VPN
  • Compliance requires no outbound calls to third-party MCP endpoints
  • You’re running the Xplorr backend on-premises
  • You want version pinning for stability

For most users, the hosted endpoint at https://mcp.xplorr.io/mcp is simpler and requires zero infrastructure.

Quick Start (One Command)

Section titled “Quick Start (One Command)”
Terminal window
docker run -d \
  --name xplorr-mcp \
  -e XPLORR_API_TOKEN=xplorr_your_token_here \
  -p 3005:3005 \
  --restart unless-stopped \
  ghcr.io/xplorrio/xplorr-mcp-server:latest

Verify it’s running:

Terminal window
curl http://localhost:3005/health

Expected response:

{"status":"ok","service":"xplorr-mcp","tools":26,"mode":"single-tenant"}

Docker Compose Setup

Section titled “Docker Compose Setup”

  1. Clone the repo

    Terminal window
    git clone https://github.com/Xplorrio/xplorr-mcp-server.git
    cd xplorr-mcp-server

  2. Configure your token

    Terminal window
    cp .env.example .env

    Edit .env and set your API token:

    Terminal window
    XPLORR_API_TOKEN=xplorr_your_token_here

    Get a token from console.xplorr.io > Settings > API Tokens.

  3. Start the container

    Terminal window
    docker compose up -d

  4. Check the logs

    Terminal window
    docker compose logs -f

    You should see: MCP server running on port 3005

  5. Verify health

    Terminal window
    curl http://localhost:3005/health

  6. Stop when needed

    Terminal window
    docker compose down

Connect Claude Desktop

Section titled “Connect Claude Desktop”

After the container is running, configure Claude Desktop to use the local MCP server.

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "xplorr": {
      "url": "http://localhost:3005/mcp"
    }
  }
}

No Authorization header needed — the token is already configured in the container’s environment.

Restart Claude Desktop. The 26 Xplorr tools appear in Claude’s tool list.

Image Tags

Section titled “Image Tags”

Images are published to GitHub Container Registry:

TagDescription
latestMost recent build from main branch
v1.2.3Specific release version
v1.2Latest patch within minor version
v1Latest minor/patch within major version

Pin to a specific version in production:

Terminal window
docker run ghcr.io/xplorrio/xplorr-mcp-server:v1.0.0 ...

Using latest in production means you get new features automatically, but also risk breaking changes. Pin a version if stability matters.

Running on a Remote Server

Section titled “Running on a Remote Server”

If the MCP server runs on a different machine than Claude Desktop (e.g., on a team server at 192.168.1.50):

{
  "mcpServers": {
    "xplorr": {
      "url": "http://192.168.1.50:3005/mcp"
    }
  }
}

Make sure port 3005 is accessible from your machine. For production, put the MCP server behind a reverse proxy with TLS.

Environment Variables

Section titled “Environment Variables”
VariableRequiredDefaultDescription
XPLORR_API_TOKENYes—Your xplorr_ API token
XPLORR_API_URLNohttps://api.xplorr.ioOverride for on-prem backends
PORTNo3005Container listen port

See the Configuration reference for details.

Troubleshooting

Section titled “Troubleshooting”

Container exits immediately

Check logs: docker logs xplorr-mcp. Most common cause: missing or invalid XPLORR_API_TOKEN.

“Connection refused” from Claude Desktop

  • Verify the container is running: docker ps | grep xplorr
  • Verify the port mapping: docker port xplorr-mcp
  • Check that nothing else is using port 3005: lsof -i :3005

Health check returns error

  • Token validation happens on the first tool call, not at startup. The health endpoint may return ok even with an invalid token.
  • If tools return auth errors, verify your token at console.xplorr.io > Settings > API Tokens.

FAQ

Section titled “FAQ”

Can I run this in Kubernetes? Yes. Use the same image (ghcr.io/xplorrio/xplorr-mcp-server) in a Deployment. Set XPLORR_API_TOKEN via a Kubernetes Secret. Expose port 3005 via a Service.

Does the container need internet access? Yes — it calls https://api.xplorr.io (or your custom XPLORR_API_URL) to fetch cost data. It doesn’t need to be publicly accessible itself.

How much memory/CPU does it need? The MCP server is lightweight. 128MB RAM and 0.25 CPU is enough for typical usage.

Section titled “Related Guides”