Build & Run (Core/Enterprise)

Build & Run: InfluxDB 3 Core / Enterprise

Workflow for building, configuring, and running the InfluxDB MCP server against InfluxDB 3 Core or Enterprise instances.

Prerequisites

• Node.js and npm (see engines in package.json for minimum version)
• A running InfluxDB 3 Core or Enterprise instance (default port: 8181). When running both Core and Enterprise on the same host for testing, each needs a distinct port (e.g., Core on 8181, Enterprise on 8281).
• An InfluxDB auth token (operator, admin, or resource token)

Environment Setup

Create a .env file in the project root (or set env vars directly). Three variables are required:

INFLUX_DB_INSTANCE_URL=http://localhost:8181/
INFLUX_DB_TOKEN=<your_token>
INFLUX_DB_PRODUCT_TYPE=core

Set INFLUX_DB_PRODUCT_TYPE to core or enterprise. The server behavior is identical for both; the type controls which tools are advertised and how config validation works.

Copy env.example as a starting point: cp env.example .env

Token types (Core/Enterprise)

Use the operator token during initial setup. Create scoped resource tokens for applications.

Build & Run

npm install        # install dependencies
npm run build      # compile TypeScript → build/
npm start          # run the server (requires build/)
npm run dev        # build + run in one step

The server communicates over stdio (stdin/stdout). All diagnostic output goes to stderr. Do not use console.log — it would corrupt the MCP transport.

Verify the server starts

npm run dev 2>&1 | head -5

Look for: [MCP] Server initialized with N tools, N resources, N prompts

Docker Workflow

Build and run via Docker when isolating the server from the host environment or deploying remotely.

npm run docker:build    # build Docker image
npm run docker:up       # start (reads .env file)
npm run docker:down     # stop
npm run docker:logs     # tail logs

When InfluxDB runs on the host machine, use host.docker.internal as the hostname in .env:

INFLUX_DB_INSTANCE_URL=http://host.docker.internal:8181/
INFLUX_DB_TOKEN=<your_token>
INFLUX_DB_PRODUCT_TYPE=enterprise

For MCP client configuration examples (local, Docker, npx), see .claude/skills/build-run-core-enterprise/references/mcp-client-configs.md.

Testing with the MCP Inspector

The MCP Inspector provides an interactive UI for testing tool calls:

npm run "MCP inspector"   # quotes required (space in script name)

This launches the inspector connected to the built server. Use it to:

• Call health_check to verify connectivity
• Call list_databases to confirm data access
• Test execute_query with a simple SQL query

Available Tools (Core/Enterprise)

All tools available for Core/Enterprise instances:

For Core/Enterprise, update_database supports the retention period only (updating retention on Core requires v3.2.0+). The cloud_* token tools are not available for Core/Enterprise.

Troubleshooting

"Configuration validation failed"

Missing or invalid env vars. Verify .env has all three required variables and INFLUX_DB_PRODUCT_TYPE is exactly core or enterprise.

Health check fails but server starts

The server can start without a reachable InfluxDB instance. Check:

1. InfluxDB is running: curl http://localhost:8181/ping
2. Token is valid (operator or admin token for full access)
3. URL has trailing slash if using the default config

"No data host configured"

INFLUX_DB_INSTANCE_URL is missing or empty. For Core/Enterprise, this must be the full URL including protocol and port.

Port confusion

InfluxDB 3 Core/Enterprise defaults to port 8181. Some example files in this repo reference port 8086 (the InfluxDB 2.x default). Always confirm which port the target instance listens on. When running both Core and Enterprise on the same host, each must use a different port — update INFLUX_DB_INSTANCE_URL accordingly for each server instance.

Additional Resources

Reference Files

• references/mcp-client-configs.md — MCP client JSON configs for Claude Desktop, Cursor, and other MCP clients (local, Docker, npx variants)