InfluxDB MCP Server

1# InfluxDB MCP Server
2 
3Model Context Protocol (MCP) server for InfluxDB 3 integration. Provides tools, resources, and prompts for interacting with InfluxDB v3 (Core/Enterprise/Cloud Dedicated/Clustered/Cloud Serverless) via MCP clients.
4 
5---
6 
7## Prerequisites
8 
9- **InfluxDB 3 Instance**: URL and token (Core/Enterprise/Cloud Serverless) or Cluster ID and tokens (Cloud Dedicated/Clustered)
10- **Node.js**: v18 or newer (for npm/npx usage)
11- **npm**: v9 or newer (for npm/npx usage)
12- **Docker**: (for Docker-based setup)
13 
14---
15 
16## Available Tools
17 
18| Tool Name                     | Description                                                       | Availability                         |
19| ----------------------------- | ----------------------------------------------------------------- | ------------------------------------ |
20| `load_database_context`       | Load optional custom database context and documentation           | All versions                         |
21| `get_help`                    | Get help and troubleshooting guidance for InfluxDB operations     | All versions                         |
22| `write_line_protocol`         | Write data using InfluxDB line protocol                           | All versions                         |
23| `create_database`             | Create a new database (with cloud-specific config options)        | All versions                         |
24| `update_database`             | Update database configuration (retention, etc.)                   | Cloud Dedicated/Clustered/Serverless |
25| `delete_database`             | Delete a database by name (irreversible)                          | All versions                         |
26| `execute_query`               | Run a SQL query against a database (supports multiple formats)    | All versions                         |
27| `get_measurements`            | List all measurements (tables) in a database                      | All versions                         |
28| `get_measurement_schema`      | Get schema (columns/types) for a measurement/table                | All versions                         |
29| `create_admin_token`          | Create a new admin token (full permissions)                       | Core/Enterprise only                 |
30| `list_admin_tokens`           | List all admin tokens (with optional filtering)                   | Core/Enterprise only                 |
31| `create_resource_token`       | Create a resource token for specific DBs and permissions          | Core/Enterprise only                 |
32| `list_resource_tokens`        | List all resource tokens (with filtering and ordering)            | Core/Enterprise only                 |
33| `delete_token`                | Delete a token by name                                            | Core/Enterprise only                 |
34| `regenerate_operator_token`   | Regenerate the operator token (dangerous/irreversible)            | Core/Enterprise only                 |
35| `cloud_list_database_tokens`  | List all database tokens for Cloud-Dedicated/Clustered cluster    | Cloud Dedicated/Clustered            |
36| `cloud_get_database_token`    | Get details of a specific database token by ID                    | Cloud Dedicated/Clustered            |
37| `cloud_create_database_token` | Create a new database token for Cloud-Dedicated/Clustered cluster | Cloud Dedicated/Clustered            |
38| `cloud_update_database_token` | Update an existing database token                                 | Cloud Dedicated/Clustered            |
39| `cloud_delete_database_token` | Delete a database token from Cloud-Dedicated/Clustered cluster    | Cloud Dedicated/Clustered            |
40| `list_databases`              | List all available databases in the instance                      | All versions                         |
41| `health_check`                | Check InfluxDB connection and health status                       | All versions                         |
42 
43---
44 
45## Available Resources
46 
47| Resource Name      | Description                                             |
48| ------------------ | ------------------------------------------------------- |
49| `influx-config`    | Read-only access to InfluxDB configuration              |
50| `influx-status`    | Real-time connection and health status                  |
51| `influx-databases` | List of all databases in the instance                   |
52| `context-file`     | Custom user-provided database context and documentation |
53 
54---
55 
56## Available Prompts
57 
58| Prompt Name      | Description                                       |
59| ---------------- | ------------------------------------------------- |
60| `list-databases` | Generate a prompt to list all available databases |
61| `check-health`   | Generate a prompt to check InfluxDB health status |
62| `load-context`   | Load custom database context and documentation    |
63 
64---
65 
66## Setup & Integration Guide
67 
68### 1. Environment Variables
69 
70#### For Core/Enterprise InfluxDB:
71 
72You must provide:
73 
74- `INFLUX_DB_INSTANCE_URL` (e.g. `http://localhost:8181/`)
75- `INFLUX_DB_TOKEN`
76- `INFLUX_DB_PRODUCT_TYPE` (`core` or `enterprise`)
77 
78Example `.env`:
79 
80```env
81INFLUX_DB_INSTANCE_URL=http://localhost:8181/
82INFLUX_DB_TOKEN=your_influxdb_token_here
83INFLUX_DB_PRODUCT_TYPE=core
84```
85 
86#### For Cloud Serverless InfluxDB:
87 
88You must provide:
89 
90- `INFLUX_DB_INSTANCE_URL` (e.g. `https://us-east-1-1.aws.cloud2.influxdata.com`)
91- `INFLUX_DB_TOKEN`
92- `INFLUX_DB_PRODUCT_TYPE` (`cloud-serverless`)
93 
94Example `.env`:
95 
96```env
97INFLUX_DB_INSTANCE_URL=https://us-east-1-1.aws.cloud2.influxdata.com
98INFLUX_DB_TOKEN=your_influxdb_token_here
99INFLUX_DB_PRODUCT_TYPE=cloud-serverless
100```
101 
102#### For Cloud Dedicated InfluxDB:
103 
104You must provide `INFLUX_DB_PRODUCT_TYPE=cloud-dedicated` and `INFLUX_DB_CLUSTER_ID`, plus one of these token combinations:
105 
106**Option 1: Database Token Only** (Query/Write operations only):
107 
108```env
109INFLUX_DB_PRODUCT_TYPE=cloud-dedicated
110INFLUX_DB_CLUSTER_ID=your_cluster_id_here
111INFLUX_DB_TOKEN=your_database_token_here
112```
113 
114**Option 2: Management Token Only** (Database management only):
115 
116```env
117INFLUX_DB_PRODUCT_TYPE=cloud-dedicated
118INFLUX_DB_CLUSTER_ID=your_cluster_id_here
119INFLUX_DB_ACCOUNT_ID=your_account_id_here
120INFLUX_DB_MANAGEMENT_TOKEN=your_management_token_here
121```
122 
123**Option 3: Both Tokens** (Full functionality):
124 
125```env
126INFLUX_DB_PRODUCT_TYPE=cloud-dedicated
127INFLUX_DB_CLUSTER_ID=your_cluster_id_here
128INFLUX_DB_ACCOUNT_ID=your_account_id_here
129INFLUX_DB_TOKEN=your_database_token_here
130INFLUX_DB_MANAGEMENT_TOKEN=your_management_token_here
131```
132 
133#### For Clustered InfluxDB:
134 
135You must provide `INFLUX_DB_PRODUCT_TYPE=clustered` and `INFLUX_DB_INSTANCE_URL`, plus one of these token combinations:
136 
137**Option 1: Database Token Only** (Query/Write operations only):
138 
139```env
140INFLUX_DB_PRODUCT_TYPE=clustered
141INFLUX_DB_INSTANCE_URL=https://your_cluster_host.com
142INFLUX_DB_TOKEN=your_database_token_here
143```
144 
145**Option 2: Management Token Only** (Database management only):
146 
147```env
148INFLUX_DB_PRODUCT_TYPE=clustered
149INFLUX_DB_INSTANCE_URL=https://your_cluster_host.com
150INFLUX_DB_MANAGEMENT_TOKEN=your_management_token_here
151```
152 
153**Option 3: Both Tokens** (Full functionality):
154 
155```env
156INFLUX_DB_PRODUCT_TYPE=clustered
157INFLUX_DB_INSTANCE_URL=https://your_cluster_host.com
158INFLUX_DB_TOKEN=your_database_token_here
159INFLUX_DB_MANAGEMENT_TOKEN=your_management_token_here
160```
161 
162See corresponding `env.<instancetype>.example` for examples and detailed info.
163 
164---
165 
166### 2. Integration with MCP Clients
167 
168#### A. Local (npm install & run)
169 
1701. **Install dependencies:**
171   ```bash
172   npm install
173   ```
1742. **Build the server:**
175   ```bash
176   npm run build
177   ```
1783. **Configure your MCP client** to use the built server. Example (see `example-local.mcp.json`):
179   ```json
180   {
181     "mcpServers": {
182       "influxdb": {
183         "command": "node",
184         "args": ["/path/to/influx-mcp-standalone/build/index.js"],
185         "env": {
186           "INFLUX_DB_INSTANCE_URL": "http://localhost:8181/",
187           "INFLUX_DB_TOKEN": "<YOUR_INFLUXDB_TOKEN>",
188           "INFLUX_DB_PRODUCT_TYPE": "core"
189         }
190       }
191     }
192   }
193   ```
194 
195#### B. Local (npx, no install/build required)
196 
1971. **Run directly with npx** (after publishing to npm, won't work yet):
198   ```json
199   {
200     "mcpServers": {
201       "influxdb": {
202         "command": "npx",
203         "args": ["-y", "@modelcontextprotocol/server-influxdb"],
204         "env": {
205           "INFLUX_DB_INSTANCE_URL": "http://localhost:8181/",
206           "INFLUX_DB_TOKEN": "<YOUR_INFLUXDB_TOKEN>",
207           "INFLUX_DB_PRODUCT_TYPE": "core"
208         }
209       }
210     }
211   }
212   ```
213 
214#### C. Docker
215 
216Before running the Docker integration, you must build the Docker image:
217 
218```bash
219# Option 1: Use docker compose (recommended)
220docker compose build
221# Option 2: Use npm script
222npm run docker:build
223```
224 
225**a) Docker with remote InfluxDB instance** (see `example-docker.mcp.json`):
226 
227```json
228{
229  "mcpServers": {
230    "influxdb": {
231      "command": "docker",
232      "args": [
233        "run",
234        "--rm",
235        "-i",
236        "-e",
237        "INFLUX_DB_INSTANCE_URL",
238        "-e",
239        "INFLUX_DB_TOKEN",
240        "-e",
241        "INFLUX_DB_PRODUCT_TYPE",
242        "mcp/influxdb"
243      ],
244      "env": {
245        "INFLUX_DB_INSTANCE_URL": "http://remote-influxdb-host:8181/",
246        "INFLUX_DB_TOKEN": "<YOUR_INFLUXDB_TOKEN>",
247        "INFLUX_DB_PRODUCT_TYPE": "core"
248      }
249    }
250  }
251}
252```
253 
254**b) Docker with InfluxDB running in Docker on the same machine** (see `example-docker.mcp.json`):
255 
256Use `host.docker.internal` as the InfluxDB URL so the MCP server container can reach the InfluxDB container:
257 
258```json
259{
260  "mcpServers": {
261    "influxdb": {
262      "command": "docker",
263      "args": [
264        "run",
265        "--rm",
266        "-i",
267        "--add-host=host.docker.internal:host-gateway",
268        "-e",
269        "INFLUX_DB_INSTANCE_URL",
270        "-e",
271        "INFLUX_DB_TOKEN",
272        "-e",
273        "INFLUX_DB_PRODUCT_TYPE",
274        "influxdb-mcp-server"
275      ],
276      "env": {
277        "INFLUX_DB_INSTANCE_URL": "http://host.docker.internal:8181/",
278        "INFLUX_DB_TOKEN": "<YOUR_INFLUXDB_TOKEN>",
279        "INFLUX_DB_PRODUCT_TYPE": "enterprise"
280      }
281    }
282  }
283}
284```
285 
286---
287 
288## Example Usage
289 
290- Use your MCP client to call tools, resources, or prompts as described above.
291- **Custom Context**: Edit the provided `context/database-context.md` file or remove it and create your own context file with "context" in the name (`.json`, `.txt`, `.md`) to provide database documentation. Use the `load_database_context` tool or `load-context` prompt to access it.
292- See the `example-*.mcp.json` files for ready-to-use configuration templates:
293  - `example-local.mcp.json` - Local development setup
294  - `example-npx.mcp.json` - NPX-based setup
295  - `example-docker.mcp.json` - Docker-based setup
296  - `example-cloud-dedicated.mcp.json` - Cloud Dedicated with all variables
297  - `example-clustered.mcp.json` - Clustered with all variables
298  - `example-cloud-serverless.mcp.json` - Cloud Serverless configuration
299- See the `env.example`, `env.cloud-dedicated.example`, `env.clustered.example`, and `env.cloud-serverless.example` files for environment variable templates.
300 
301---
302 
303## Support & Troubleshooting
304 
305- Use the `get_help` tool for built-in help and troubleshooting.
306- For connection issues, check your environment variables and InfluxDB instance status.
307- For advanced configuration, see the comments in the example `.env` and MCP config files.
308 
309---
310 
311## License
312 
313[MIT](LICENSE)
314