influxdb-mcp-server/DOCKER.md

Docker Deployment Guide for InfluxDB MCP Server

This guide explains how to run the InfluxDB MCP Server in Docker, similar to the MCP Toolkit in Docker Desktop.

Table of Contents

• Quick Start
• Docker Compose Setup
• Configuration
• Using with Docker Desktop MCP Support
• Using with Claude Desktop
• Networking Considerations
• Building the Image
• Troubleshooting
• Advanced Configuration

---

Quick Start

Prerequisites

• Docker installed (Docker Desktop 4.34+ for MCP support)
• InfluxDB v2 instance running
• InfluxDB authentication token

1. Create Environment File

Create a .env file in the project root:

# Copy the example
cp .env.example .env

# Edit with your details
nano .env

Add your InfluxDB details:

INFLUX_URL=http://localhost:8086
INFLUX_TOKEN=your_influxdb_token_here
INFLUX_ORG=your_organization_name

2. Build and Run

# Build and start the container
docker-compose up -d

# Check logs
docker-compose logs -f

# Stop the container
docker-compose down

---

Docker Compose Setup

The provided docker-compose.yml includes:

• Multi-stage build for optimized image size
• Host networking for easy InfluxDB access
• Security hardening (read-only filesystem, non-root user)
• Resource limits (256MB RAM, 0.5 CPU)
• Health checks for container monitoring
• Automatic restarts unless manually stopped

Basic Usage

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f influxdb-mcp-server

# Restart
docker-compose restart

# Stop
docker-compose down

# Rebuild after code changes
docker-compose up -d --build

---

Configuration

Environment Variables

Configure via .env file or docker-compose environment section:

Variable	Required	Default	Description
INFLUX_URL	Yes	http://localhost:8086	InfluxDB server URL
INFLUX_TOKEN	Yes	-	Authentication token
INFLUX_ORG	Yes	-	Organization name
NODE_ENV	No	production	Node environment

Getting an InfluxDB Token

1. Log into InfluxDB UI (usually at http://localhost:8086)
2. Navigate to Data → Tokens or Load Data → API Tokens
3. Click Generate API Token
4. Choose All Access Token or create custom permissions:
   • Read/Write access to buckets you need
   • Read access to organizations
5. Copy the token immediately (shown only once)

Token Permissions

For full functionality, the token should have:

• Read: buckets, orgs, tasks, dashboards
• Write: buckets (if you plan to write data)
• Delete: buckets (if you plan to delete buckets)

---

Using with Docker Desktop MCP Support

Docker Desktop 4.34+ includes native MCP support in the AI tools section.

Setup

1. Build the image:

   docker-compose build
   

2. Tag for Docker Desktop:

   docker tag influxdb-mcp-server:latest influxdb-mcp-server:latest
   

3. Configure in Docker Desktop:

   Open Docker Desktop settings and add to MCP servers:

   {
     "mcpServers": {
       "influxdb": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "--network=host",
           "-e", "INFLUX_URL=http://localhost:8086",
           "-e", "INFLUX_TOKEN=your_token_here",
           "-e", "INFLUX_ORG=your_org",
           "influxdb-mcp-server:latest"
         ]
       }
     }
   }
   

4. Restart Docker Desktop to load the MCP server

Verification

The MCP server should appear in Docker Desktop's AI tools section. You can then use it with any integrated AI assistant.

---

Using with Claude Desktop

Method 1: Using Docker Directly

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "influxdb": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=host",
        "-e", "INFLUX_URL=http://localhost:8086",
        "-e", "INFLUX_TOKEN=your_influxdb_token",
        "-e", "INFLUX_ORG=your_organization",
        "influxdb-mcp-server:latest"
      ]
    }
  }
}

Method 2: Using Docker Compose

Create a wrapper script run-mcp.sh:

#!/bin/bash
docker-compose run --rm influxdb-mcp-server

Make it executable:

chmod +x run-mcp.sh

Configure Claude Desktop:

{
  "mcpServers": {
    "influxdb": {
      "command": "/Users/felix/Nextcloud/AI/projects/influxdb-mcp-server/run-mcp.sh"
    }
  }
}

Restart Claude Desktop

After configuration changes, fully quit and restart Claude Desktop.

---

Networking Considerations

Host Network Mode (Default)

The default configuration uses network_mode: host, which:

• ✅ Simplest setup
• ✅ Direct access to InfluxDB on local network
• ✅ No port mapping needed
• ⚠️ Linux-only feature (works differently on macOS/Windows)

Bridge Network Mode

If your InfluxDB is also in Docker, use bridge networking:

1. Update docker-compose.yml:

   version: '3.8'
   
   services:
     influxdb-mcp-server:
       build: .
       environment:
         - INFLUX_URL=http://influxdb:8086
         - INFLUX_TOKEN=${INFLUX_TOKEN}
         - INFLUX_ORG=${INFLUX_ORG}
       networks:
         - influx-network
       # Remove network_mode: host
   
   networks:
     influx-network:
       external: true  # If InfluxDB network exists
       # Or create new network:
       # driver: bridge
   

2. Connect to InfluxDB network:

   # Find InfluxDB network
   docker network ls
   
   # Update docker-compose.yml with correct network name
   # Then start
   docker-compose up -d
   

macOS/Windows Considerations

On macOS and Windows, Docker runs in a VM:

• host networking works differently
• Use explicit URLs like http://host.docker.internal:8086
• Or use bridge networking with proper network setup

Running with InfluxDB in Docker

If you're running InfluxDB itself in Docker, here's a complete setup:

version: '3.8'

services:
  influxdb:
    image: influxdb:2.7-alpine
    container_name: influxdb
    ports:
      - "8086:8086"
    volumes:
      - influxdb-data:/var/lib/influxdb2
      - influxdb-config:/etc/influxdb2
    environment:
      - DOCKER_INFLUXDB_INIT_MODE=setup
      - DOCKER_INFLUXDB_INIT_USERNAME=admin
      - DOCKER_INFLUXDB_INIT_PASSWORD=adminpassword
      - DOCKER_INFLUXDB_INIT_ORG=myorg
      - DOCKER_INFLUXDB_INIT_BUCKET=mybucket
      - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=mytoken
    networks:
      - influx-network

  influxdb-mcp-server:
    build: .
    container_name: influxdb-mcp-server
    environment:
      - INFLUX_URL=http://influxdb:8086
      - INFLUX_TOKEN=mytoken
      - INFLUX_ORG=myorg
    depends_on:
      - influxdb
    networks:
      - influx-network

networks:
  influx-network:
    driver: bridge

volumes:
  influxdb-data:
  influxdb-config:

---

Building the Image

Build Locally

# Using docker-compose
docker-compose build

# Using docker directly
docker build -t influxdb-mcp-server:latest .

# Build with no cache
docker-compose build --no-cache

Build Arguments

The Dockerfile supports Node.js version customization:

docker build \
  --build-arg NODE_VERSION=20 \
  -t influxdb-mcp-server:latest \
  .

Multi-Architecture Builds

For running on different platforms (e.g., Raspberry Pi):

# Enable buildx
docker buildx create --use

# Build for multiple architectures
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t influxdb-mcp-server:latest \
  --push \
  .

---

Troubleshooting

Container Won't Start

Check logs:

docker-compose logs influxdb-mcp-server

Common issues:

1. Missing environment variables

   • Ensure .env file exists
   • Check variable names match exactly (INFLUX_URL, INFLUX_TOKEN, INFLUX_ORG)

2. Cannot reach InfluxDB

   • Verify INFLUX_URL is correct
   • Check network connectivity: docker exec influxdb-mcp-server ping influxdb
   • Try IP address instead of hostname
   • Check InfluxDB is running: curl http://localhost:8086/health

3. Permission denied

   • Container runs as non-root user
   • Check file permissions if mounting volumes

Container Restarting Every 30 Seconds

Symptom: You see repeated connection messages in the logs:

InfluxDB MCP Server running on stdio
Successfully connected to InfluxDB
Server: influxdb (v2.7.10)
Status: pass
InfluxDB MCP Server running on stdio
Successfully connected to InfluxDB
...

Cause: MCP servers communicate via stdio (stdin/stdout). Docker healthchecks interfere with stdio, causing the healthcheck to fail and Docker to restart the container.

Solution: The healthcheck is now disabled by default in docker-compose.yml:

# In docker-compose.yml
healthcheck:
  disable: true

# And restart policy is set to "no" since MCP servers run on-demand
restart: "no"

If you have an older version, update your docker-compose.yml with these settings and rebuild:

docker-compose down
docker-compose up -d --build

Connection Errors

Test InfluxDB connection:

# Enter container
docker exec -it influxdb-mcp-server sh

# Test connection using wget (Alpine doesn't have curl by default)
wget -O- http://localhost:8086/health

Check environment variables:

docker exec influxdb-mcp-server env | grep INFLUX_

Test token authentication:

docker exec influxdb-mcp-server sh -c '
  wget --header="Authorization: Token $INFLUX_TOKEN" \
       -O- "$INFLUX_URL/api/v2/buckets?org=$INFLUX_ORG"
'

MCP Communication Issues

Verify stdio communication:

The MCP server communicates via stdio (stdin/stdout), not network ports.

# Test directly
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | \
  docker run -i --rm \
  -e INFLUX_URL=http://localhost:8086 \
  -e INFLUX_TOKEN=your_token \
  -e INFLUX_ORG=your_org \
  influxdb-mcp-server:latest

Performance Issues

Check resource usage:

docker stats influxdb-mcp-server

Adjust resource limits in docker-compose.yml:

deploy:
  resources:
    limits:
      cpus: '1.0'      # Increase CPU limit
      memory: 512M     # Increase memory limit

InfluxDB Connection Timeout

If queries are slow or timing out:

1. Increase query timeout in the client code
2. Optimize Flux queries - use filters and limits
3. Check InfluxDB performance - ensure it's not overloaded
4. Increase container memory if processing large results

---

Advanced Configuration

Running Multiple Instances

Run multiple MCP servers for different InfluxDB instances:

# docker-compose.yml
version: '3.8'

services:
  influxdb-mcp-prod:
    build: .
    container_name: influxdb-mcp-prod
    environment:
      - INFLUX_URL=http://influxdb-prod:8086
      - INFLUX_TOKEN=${INFLUX_TOKEN_PROD}
      - INFLUX_ORG=production
    network_mode: host

  influxdb-mcp-dev:
    build: .
    container_name: influxdb-mcp-dev
    environment:
      - INFLUX_URL=http://influxdb-dev:8086
      - INFLUX_TOKEN=${INFLUX_TOKEN_DEV}
      - INFLUX_ORG=development
    network_mode: host

Custom Logging

Change log format:

# docker-compose.yml
logging:
  driver: "json-file"
  options:
    max-size: "50m"
    max-file: "5"
    labels: "influxdb-mcp-server"

Use external logging:

logging:
  driver: "syslog"
  options:
    syslog-address: "tcp://192.168.1.100:514"

Monitoring with Prometheus

Add labels for monitoring:

labels:
  - "prometheus.scrape=true"
  - "prometheus.port=9090"

Read-Only Filesystem

The container uses a read-only root filesystem for security:

read_only: true
tmpfs:
  - /tmp      # Allows temp file writes

To allow writes to specific locations:

volumes:
  - ./data:/app/data:rw
read_only: true

Custom Node.js Options

Pass Node.js flags:

command: ["node", "--max-old-space-size=128", "dist/index.js"]

Query Result Size Limits

For large query results, adjust Node.js memory:

environment:
  - NODE_OPTIONS=--max-old-space-size=512

---

Docker Image Details

Image Layers

1. Base: node:20-alpine (~40MB)
2. Dependencies: Production npm packages (~30MB)
3. Application: Compiled TypeScript code (~1MB)
4. Total: ~70-100MB

Security Features

• ✅ Non-root user (nodejs:nodejs)
• ✅ Read-only root filesystem
• ✅ No new privileges
• ✅ Minimal base image (Alpine)
• ✅ Multi-stage build (no dev dependencies)
• ✅ No shell access required

Optimization

• Multi-stage build reduces image size
• Alpine Linux base for minimal footprint
• Production dependencies only in final image
• No development tools included

---

Integration Examples

Docker Desktop AI Assistant

Once configured in Docker Desktop, use natural language:

You: "List all my InfluxDB buckets"
AI: Uses influxdb MCP resource to get buckets
    → Returns list of buckets

You: "Query CPU usage for the last hour"
AI: Uses influxdb query_flux tool
    → Returns CPU metrics

You: "Write temperature sensor data"
AI: Uses influxdb write_data tool
    → Data written successfully

CI/CD Pipeline

# .github/workflows/docker.yml
name: Build and Push

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build Docker image
        run: docker build -t influxdb-mcp-server:latest .

      - name: Test
        run: |
          docker run --rm \
            -e INFLUX_URL=http://test:8086 \
            -e INFLUX_TOKEN=test \
            -e INFLUX_ORG=test \
            influxdb-mcp-server:latest \
            node -e "console.log('OK')"

---

Comparison with Direct Installation

Feature	Docker	Direct
Setup Complexity	Medium	Easy
Isolation	✅ Excellent	⚠️ None
Resource Usage	~100MB	~80MB
Updates	Rebuild image	npm update
Portability	✅ Excellent	⚠️ Platform dependent
Debugging	Harder	Easier
Security	✅ Sandboxed	⚠️ Full system access
MCP Desktop Integration	✅ Native	✅ Native

---

Next Steps

1. ✅ Built and configured the Docker container
2. ✅ Set up environment variables
3. ✅ Started the service with docker-compose
4. → Configure Claude Desktop or Docker Desktop to use it
5. → Test with commands like "list all buckets"
6. → Monitor logs for issues

---

Resources

• Docker Documentation: https://docs.docker.com/
• Docker Compose Reference: https://docs.docker.com/compose/
• MCP Specification: https://modelcontextprotocol.io/
• InfluxDB v2 API: https://docs.influxdata.com/influxdb/v2/api/
• Docker Desktop MCP: https://docs.docker.com/desktop/mcp/
• InfluxDB Docker Image: https://hub.docker.com/_/influxdb

---

Getting Help

If you encounter issues:

1. Check logs: docker-compose logs -f
2. Verify environment: docker exec influxdb-mcp-server env
3. Test InfluxDB connection from container
4. Review this documentation
5. Check InfluxDB logs for API errors
6. Verify token permissions in InfluxDB UI

The MCP server is now fully containerized and ready for use with Docker Desktop's AI tools or Claude Desktop! 🐳📊🤖