f2daz/influxdb-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Felix Zösch
2025-12-11 20:30:12 +01:00
commit 3e23474476
21 changed files with 5327 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

738
DOCKER.md Normal file
View File

@@ -0,0 +1,738 @@
# 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! 🐳📊🤖