| name | Build & Run (Core/Enterprise) |
| description | This skill should be used when the user asks to "build the MCP server", "run the server", "set up for InfluxDB Core", "set up for InfluxDB Enterprise", "configure the server", "start the MCP server", "run with Docker", "test the MCP server connection", "use the MCP inspector", "set up .env", "what npm commands are available", or needs to build, configure, run, or troubleshoot this MCP server against InfluxDB 3 Core or InfluxDB 3 Enterprise. |
| version | 0.1.0 |
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)
| Token Type | Purpose | How to obtain |
|---|
| Operator | Full admin, bootstraps the instance | Printed on first influxdb3 serve start |
| Admin | Full admin except managing other admins | Created via create_admin_token tool |
| Resource | Scoped read/write on specific databases | Created via create_resource_token tool |
Use the operator token during initial setup. Create scoped resource tokens for
applications.
Build & Run
npm install
npm run build
npm start
npm run dev
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
npm run docker:up
npm run docker:down
npm run docker: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"
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:
| Tool | Description |
|---|
health_check | Verify connection and health status |
list_databases | List all databases |
create_database | Create a new database |
update_database | Update retention period (Core requires v3.2.0+) |
delete_database | Delete a database |
execute_query | Run SQL queries |
get_measurements | List tables in a database |
get_measurement_schema | Show columns/types for a table |
write_line_protocol | Write data via line protocol |
create_admin_token | Create named admin token |
list_admin_tokens | List admin tokens |
create_resource_token | Create scoped resource token |
list_resource_tokens | List resource tokens |
delete_token | Delete a token by name |
regenerate_operator_token | Regenerate operator token (destructive) |
get_help | Built-in help and troubleshooting |
load_database_context | Load custom context from context/ |
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:
- InfluxDB is running:
curl http://localhost:8181/ping
- Token is valid (operator or admin token for full access)
- 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)
