# AWS Labs Timestream for InfluxDB MCP Server

An AWS Labs Model Context Protocol (MCP) server for Timestream for InfluxDB. This server provides tools to interact with AWS Timestream for InfluxDB APIs, allowing you to create and manage database instances, clusters, parameter groups, and more. It also includes tools to interact with InfluxDB's write and query APIs.

## Features

- Create, update, list, describe, and delete Timestream for InfluxDB database instances
- Create, update, list, describe, and delete Timestream for InfluxDB database clusters
- Manage DB parameter groups
- Tag management for Timestream for InfluxDB resources
- Manage InfluxDB 2 buckets and organizations
- Write and query data using InfluxDB 2 APIs


## Pre-requisites
1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
2. Install Python using `uv python install 3.10`
3. Set up AWS credentials with access to AWS services
    - You need an AWS account with appropriate permissions
    - Configure AWS credentials with `aws configure` or environment variables
    - Consider starting with Read-only permission if you don't want the LLM to modify any resources

## Installation

| Kiro | Cursor | VS Code |
|:----:|:------:|:-------:|
| [![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=awslabs.timestream-for-influxdb-mcp-server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.timestream-for-influxdb-mcp-server%40latest%22%5D%2C%22env%22%3A%7B%22AWS_PROFILE%22%3A%22your-aws-profile%22%2C%22AWS_REGION%22%3A%22us-east-1%22%2C%22FASTMCP_LOG_LEVEL%22%3A%22ERROR%22%7D%7D) | [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en/install-mcp?name=awslabs.timestream-for-influxdb-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMudGltZXN0cmVhbS1mb3ItaW5mbHV4ZGItbWNwLXNlcnZlckBsYXRlc3QiLCJlbnYiOnsiQVdTX1BST0ZJTEUiOiJ5b3VyLWF3cy1wcm9maWxlIiwiQVdTX1JFR0lPTiI6InVzLWVhc3QtMSIsIkZBU1RNQ1BfTE9HX0xFVkVMIjoiRVJST1IifSwiZGlzYWJsZWQiOmZhbHNlLCJhdXRvQXBwcm92ZSI6W119) | [![Install on VS Code](https://img.shields.io/badge/Install_on-VS_Code-FF9900?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Timestream%20for%20InfluxDB%20MCP%20Server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.timestream-for-influxdb-mcp-server%40latest%22%5D%2C%22env%22%3A%7B%22AWS_PROFILE%22%3A%22your-aws-profile%22%2C%22AWS_REGION%22%3A%22us-east-1%22%2C%22FASTMCP_LOG_LEVEL%22%3A%22ERROR%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D) |

You can modify the settings of your MCP client to run your local server (e.g. for Kiro, `~/.kiro/settings/mcp.json`)

```json
{
  "mcpServers": {
    "awslabs.timestream-for-influxdb-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.timestream-for-influxdb-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "INFLUXDB_URL": "https://your-influxdb-endpoint:8086",
        "INFLUXDB_TOKEN": "your-influxdb-token",
        "INFLUXDB_ORG": "your-influxdb-org",
        "INFLUXDB_WRITE_MODE": "false",
        "ALLOW_WRITE": "false",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```
### Windows Installation

For Windows users, the MCP server configuration format is slightly different:

```json
{
  "mcpServers": {
    "awslabs.timestream-for-influxdb-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.timestream-for-influxdb-mcp-server@latest",
        "awslabs.timestream-for-influxdb-mcp-server.exe"
      ],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "INFLUXDB_URL": "https://your-influxdb-endpoint:8086",
        "INFLUXDB_TOKEN": "your-influxdb-token",
        "INFLUXDB_ORG": "your-influxdb-org",
        "INFLUXDB_WRITE_MODE": "false",
        "ALLOW_WRITE": "false",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}
```

### InfluxDB Connection Security

InfluxDB tools use the `INFLUXDB_URL`, `INFLUXDB_TOKEN`, and `INFLUXDB_ORG`
environment variables when no connection parameters are supplied in a tool call.

Connection parameters are treated as a single trust boundary:

- If a tool call supplies any connection parameter, it must supply all parameters
  required by that tool. Server environment credentials are never used to complete
  a partial caller-supplied configuration.
- A caller-supplied URL must match `INFLUXDB_URL` or an entry in the optional,
  comma-separated `INFLUXDB_ALLOWED_URLS` environment variable.
- Configure additional endpoints before allowing tool calls to target them. For
  example, set `INFLUXDB_ALLOWED_URLS` to
  `https://influxdb-a.example.com:8086,https://influxdb-b.example.com:8086`.

This is a breaking change for clients that previously supplied only some connection
parameters and relied on environment-variable fallback for the others. Update those
clients to either omit all connection parameters or provide a complete configuration
for an operator-approved URL.


### Available Tools

The Timestream for InfluxDB MCP server provides the following tools:

#### AWS Timestream for InfluxDB Management

##### Database Cluster Management
- `CreateDbCluster`: Create a new Timestream for InfluxDB database cluster
- `GetDbCluster`: Retrieve information about a specific DB cluster
- `DeleteDbCluster`: Delete a Timestream for InfluxDB database cluster
- `ListDbClusters`: List all Timestream for InfluxDB database clusters
- `UpdateDbCluster`: Update a Timestream for InfluxDB database cluster
- `ListDbClusters`: List all Timestream for InfluxDB database clusters
- `ListDbInstancesForCluster`: List DB instances belonging to a specific cluster
- `ListClustersByStatus`: List DB clusters filtered by status

##### Database Instance Management
- `CreateDbInstance`: Create a new Timestream for InfluxDB database instance
- `GetDbInstance`: Retrieve information about a specific DB instance
- `DeleteDbInstance`: Delete a Timestream for InfluxDB database instance
- `ListDbInstances`: List all Timestream for InfluxDB database instances
- `UpdateDbInstance`: Update a Timestream for InfluxDB database instance
- `ListDbInstancesByStatus`: List DB instances filtered by status

##### Parameter Group Management
- `CreateDbParamGroup`: Create a new DB parameter group
- `GetDbParameterGroup`: Retrieve information about a specific DB parameter group
- `ListDbParamGroups`: List all DB parameter groups

##### Tag Management
- `ListTagsForResource`: List all tags on a Timestream for InfluxDB resource
- `TagResource`: Add tags to a Timestream for InfluxDB resource
- `UntagResource`: Remove tags from a Timestream for InfluxDB resource

#### InfluxDB Data Operations

##### Write API
- `InfluxDBWritePoints`: Write data points to InfluxDB
- `InfluxDBWriteLP`: Write data in Line Protocol format to InfluxDB

##### Query API
- `InfluxDBQuery`: Query data from InfluxDB using Flux query language

##### Bucket Management
- `InfluxDBListBuckets`: List all buckets in InfluxDB
- `InfluxDBCreateBucket`: Create a new bucket in InfluxDB

##### Organization Management
- `InfluxDBListOrgs`: List all organizations in InfluxDB
- `InfluxDBCreateOrg`: Create a new organization in InfluxDB

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AWS_PROFILE` | No | — | AWS profile for control-plane operations |
| `AWS_REGION` | No | `us-east-1` | AWS region |
| `INFLUXDB_URL` | No | — | InfluxDB v2 endpoint URL (e.g. `https://host:8086`) |
| `INFLUXDB_TOKEN` | No | — | InfluxDB v2 authentication token |
| `INFLUXDB_ORG` | No | — | InfluxDB v2 organization name |
| `INFLUXDB_ALLOWED_URLS` | No | — | Comma-separated list of additional approved InfluxDB URLs |
| `INFLUXDB_WRITE_MODE` | No | `false` | Enable write-producing Flux operations in queries (see below) |
| `ALLOW_WRITE` | No | `false` | Enable mutating tools (create/update/delete and data-plane writes). Operator-controlled; see below |
| `FASTMCP_LOG_LEVEL` | No | — | Logging level (`ERROR`, `WARNING`, `INFO`, `DEBUG`) |

### Write Mode

By default, the server runs **read-only**: all mutating tools (create/update/delete DB clusters and instances, tag/untag, create parameter group, and the data-plane writes `InfluxDBWritePoints`, `InfluxDBWriteLP`, `InfluxDBCreateBucket`, `InfluxDBCreateOrg`) are refused. Write authorization is **operator-controlled** via the `ALLOW_WRITE` environment variable and is evaluated once at startup — it is **not** a tool parameter and cannot be set or overridden by a tool caller. To enable mutating tools, start the server with:

```
ALLOW_WRITE=true
```

When `ALLOW_WRITE` is not enabled, mutating tools raise an error and never call the underlying AWS or InfluxDB APIs.

### Flux Query Write Mode

By default, the `InfluxDBQuery` tool rejects Flux queries that contain write-producing operations such as `to()`, `experimental.to()`, and `wideTo()`. This ensures that the query tool behaves as read-only, even when the configured InfluxDB token has write permissions.

To enable write-producing Flux operations through the query tool, set:

```
INFLUXDB_WRITE_MODE=true
```

This setting is operator-controlled and cannot be overridden by tool callers.

> **Best practice:** For deployments that need both read and write capabilities, configure a **read-only InfluxDB token** for general use and enable writes with `ALLOW_WRITE=true` (and `INFLUXDB_WRITE_MODE=true` for Flux-query writes) only when needed. This provides the strongest data integrity guarantee regardless of the MCP server's write-mode setting.