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](#quick-start)
- [Docker Compose Setup](#docker-compose-setup)
- [Configuration](#configuration)
- [Using with Docker Desktop MCP Support](#using-with-docker-desktop-mcp-support)
- [Using with Claude Desktop](#using-with-claude-desktop)
- [Networking Considerations](#networking-considerations)
- [Building the Image](#building-the-image)
- [Troubleshooting](#troubleshooting)
- [Advanced Configuration](#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:

```bash
# Copy the example
cp .env.example .env

# Edit with your details
nano .env
```

Add your InfluxDB details:

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

### 2. Build and Run

```bash
# 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

```bash
# 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:**
   ```bash
   docker-compose build
   ```

2. **Tag for Docker Desktop:**
   ```bash
   docker tag influxdb-mcp-server:latest influxdb-mcp-server:latest
   ```

3. **Configure in Docker Desktop:**

   Open Docker Desktop settings and add to MCP servers:

   ```json
   {
     "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):

```json
{
  "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`:

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

Make it executable:
```bash
chmod +x run-mcp.sh
```

Configure Claude Desktop:

```json
{
  "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:**

   ```yaml
   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:**

   ```bash
   # 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:

```yaml
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

```bash
# 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:

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

### Multi-Architecture Builds

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

```bash
# 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:**
```bash
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:

```yaml
# 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:

```bash
docker-compose down
docker-compose up -d --build
```

### Connection Errors

**Test InfluxDB connection:**

```bash
# 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:**

```bash
docker exec influxdb-mcp-server env | grep INFLUX_
```

**Test token authentication:**

```bash
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.

```bash
# 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:**

```bash
docker stats influxdb-mcp-server
```

**Adjust resource limits** in docker-compose.yml:

```yaml
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:

```yaml
# 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:**

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

**Use external logging:**

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

### Monitoring with Prometheus

Add labels for monitoring:

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

### Read-Only Filesystem

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

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

To allow writes to specific locations:

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

### Custom Node.js Options

Pass Node.js flags:

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

### Query Result Size Limits

For large query results, adjust Node.js memory:

```yaml
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

```yaml
# .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! 🐳📊🤖