influxdb-v1-mcp

A read-only Model Context Protocol (MCP) server for InfluxDB v1.x.

It speaks MCP over stdio, so it is launched on demand by an MCP client (such as Devin) and exits when the session ends. There is no long-running HTTP MCP server to host or keep alive — you just point the client at a command (either npx or docker run).

Features

• Read-only by design. Only SELECT, SHOW, and EXPLAIN statements are allowed. Writes, deletes, schema changes, user management, and SELECT ... INTO are rejected before they ever reach InfluxDB. Queries are also sent over HTTP GET, which InfluxDB rejects for data-mutating statements.
• Runs via npx or Docker. No global install needed.
• Stdio transport. No ports to expose, no server to babysit.
• Schema discovery tools for databases, measurements, retention policies, tag keys, and field keys.
• Flexible auth: basic auth (username/password) or v1.8+ token auth.

Tools

| Tool | Description | Underlying query | | --- | --- | --- | | influxdb_query | Run any read-only InfluxQL query | SELECT / SHOW / EXPLAIN ... | | list_databases | List all databases | SHOW DATABASES | | list_measurements | List measurements in a database | SHOW MEASUREMENTS | | list_retention_policies | List retention policies | SHOW RETENTION POLICIES | | show_tag_keys | List tag keys (optionally per measurement) | SHOW TAG KEYS | | show_field_keys | List field keys and types (optionally per measurement) | SHOW FIELD KEYS | | ping | Check connectivity and report the InfluxDB version | GET /ping |

Configuration

All configuration is via environment variables:

| Variable | Required | Default | Description | | --- | --- | --- | --- | | INFLUX_URL | no | http://localhost:8086 | Base URL of the InfluxDB v1 server | | INFLUX_DATABASE | no | — | Default database used when a tool call omits one | | INFLUX_USERNAME | no | — | Basic auth username | | INFLUX_PASSWORD | no | — | Basic auth password | | INFLUX_TOKEN | no | — | Bearer/JWT token (v1.8+); overrides basic auth | | INFLUX_TIMEOUT_MS | no | 15000 | Per-request timeout in milliseconds | | INFLUX_CONTEXT | no | — | Inline DB reference appended to the MCP instructions (see below) | | INFLUX_CONTEXT_FILE | no | — | Path to a file appended to the instructions (handy for Docker mounts) |

See .env.example.

Giving the AI persistent DB knowledge (INFLUX_CONTEXT)

The server sends an instructions block to the client on every connect. Anything you put in INFLUX_CONTEXT (or a file referenced by INFLUX_CONTEXT_FILE) is appended to it, so the AI knows your measurements, tags, fields, units, and semantics without rediscovering them each session.

Set it in the MCP connector's env block, e.g.:

"env": {
  "INFLUX_URL": "https://influx.example.com:8086",
  "INFLUX_DATABASE": "telemetry",
  "INFLUX_CONTEXT": "Measurements:\n- cpu_1h: hourly CPU rollup. tags: host, region. fields: usage_user, usage_system (percent). Retention: 90d.\n- requests_raw: per-request events. tags: service, endpoint. fields: latency_ms (gauge). High cardinality — always filter by time and service."
}

For large references, mount a file into the container and point at it:

docker run --rm -i \
  -e INFLUX_URL -e INFLUX_DATABASE \
  -e INFLUX_CONTEXT_FILE=/config/influx-context.md \
  -v /path/to/influx-context.md:/config/influx-context.md:ro \
  your-registry/influxdb-v1-mcp:latest

Usage with Devin (and other MCP clients)

The server is configured as an MCP server using a command + args + env block. Pick one of the two methods below.

Option A — npx (no Docker)

{
  "mcpServers": {
    "influxdb-v1": {
      "command": "npx",
      "args": ["-y", "@millicast/influxdb-v1-mcp"],
      "env": {
        "INFLUX_URL": "https://influxdb.example.com:8086",
        "INFLUX_DATABASE": "telemetry",
        "INFLUX_USERNAME": "readonly_user",
        "INFLUX_PASSWORD": "••••••"
      }
    }
  }
}

npx requires the package to be published to a registry (see Publishing). For a private/local checkout, you can instead point at the built file: "command": "node", "args": ["/abs/path/dist/index.js"].

Option B — Docker image (recommended for hosting)

Build and host the image once, then have the client run it on demand:

{
  "mcpServers": {
    "influxdb-v1": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "INFLUX_URL",
        "-e", "INFLUX_DATABASE",
        "-e", "INFLUX_USERNAME",
        "-e", "INFLUX_PASSWORD",
        "your-registry/influxdb-v1-mcp:latest"
      ],
      "env": {
        "INFLUX_URL": "https://influxdb.example.com:8086",
        "INFLUX_DATABASE": "telemetry",
        "INFLUX_USERNAME": "readonly_user",
        "INFLUX_PASSWORD": "••••••"
      }
    }
  }
}

The -i flag is required — MCP communicates over stdin/stdout. --rm cleans up the container after each session. Each variable is passed through with -e NAME (value taken from the client's env block).

Building and running the Docker image

This project uses pnpm (pinned via packageManager in package.json and installed through corepack inside the build).

# Build
docker build -t influxdb-v1-mcp .

# Connectivity self-test (no MCP session; verifies config + reaches InfluxDB)
docker run --rm -e INFLUX_URL=https://influxdb.example.com:8086 \
  influxdb-v1-mcp --self-test

# Run as an MCP server over stdio (normally launched by the client, not by hand)
docker run --rm -i -e INFLUX_URL=https://influxdb.example.com:8086 influxdb-v1-mcp

Push to a registry to host it

docker tag influxdb-v1-mcp your-registry/influxdb-v1-mcp:1.0.0
docker push your-registry/influxdb-v1-mcp:1.0.0

Once pushed, any host with Docker can run it on demand via the Option B config above — nothing needs to stay running between sessions.

Local development & testing

1. Install + build:

   corepack enable          # makes pnpm available
   pnpm install
   pnpm run build           # compile TypeScript to dist/

2. Add your connection details to the gitignored .env file (host, username/password, etc.). See .env.example for the full list of variables.

3. Verify connectivity (pings InfluxDB using .env):

   pnpm run selftest

4. Full end-to-end test — launches the server, runs an MCP handshake, then calls ping and list_databases against your InfluxDB:

   pnpm run test:local

5. Run the server directly (stdio, config from .env):

   pnpm run start:local

These scripts load .env via Node's built-in --env-file flag (Node 20.6+), so no extra dependency is needed. pnpm run dev runs tsc in watch mode.

Test the Docker image locally

Once Docker is running, the same .env file works with --env-file:

docker build -t influxdb-v1-mcp .
docker run --rm --env-file .env influxdb-v1-mcp --self-test   # connectivity check
docker run --rm -i --env-file .env influxdb-v1-mcp            # run as MCP server

Quick manual MCP check (no InfluxDB needed)

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node dist/index.js

Publishing to npm

This package is published under the @millicast scope. To enable the npx @millicast/influxdb-v1-mcp workflow:

npm whoami    # ensure you're logged in with access to the @millicast org
pnpm run build
npm publish   # publishConfig.access=public + prepublishOnly (rebuilds dist/) are already set

Read-only guarantees

1. Statement allow-list: every statement must start with SELECT, SHOW, or EXPLAIN.
2. Keyword deny-list: INSERT, DELETE, DROP, CREATE, ALTER, GRANT, REVOKE, KILL, SET, UPDATE, and INTO are rejected anywhere in a statement.
3. HTTP GET only: all queries use GET /query, which InfluxDB refuses to use for data-mutating statements.

For maximum safety, also point the server at an InfluxDB user that only has read permissions.

License

MIT