home / mcp / iotdb mcp server

IoTDB MCP Server

Apache IoTDB MCP Server

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "apache-iotdb-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
        "run",
        "server.py"
      ],
      "env": {
        "IOTDB_HOST": "127.0.0.1",
        "IOTDB_PORT": "6667",
        "IOTDB_USER": "root",
        "IOTDB_DATABASE": "test",
        "IOTDB_PASSWORD": "root",
        "IOTDB_EXPORT_PATH": "/path/to/export/folder",
        "IOTDB_SQL_DIALECT": "table"
      }
    }
  }
}

IoTDB MCP Server enables you to run SQL queries and interact with IoTDB through two SQL dialects (Tree Model and Table Model) using a configurable MCP interface. It provides practical tooling for metadata discovery, data querying, and data export, all accessible via a consistent MCP client workflow.

How to use

You connect to the IoTDB MCP Server through an MCP client and choose a dialect for your queries. The Tree Model lets you issue SHOW/COUNT queries to read metadata and perform explorations like listing databases, timeseries, devices, and counts. The Table Model provides read access to data and supports exporting results. You can switch between dialects by configuring IOTDB_SQL_DIALECT to either tree or table.

Typical workflows you can perform: query metadata (SHOW/COUNT) using Tree Model, run SELECT queries to fetch data, and export results to CSV or Excel for reporting. When using the Claude Desktop integration, you’ll launch the MCP server as a local process and provide IoTDB connection details via environment variables.

How to install

Prerequisites you need before installation:

Python environment
uv package manager
IoTDB installation
MCP server dependencies

Step-by-step setup for the IoTDB MCP Server environment and development workflow:

# Clone the MCP server repository
git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb-mcp-server

# Create and activate a Python virtual environment (Windows users adapt paths)
uv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install development dependencies
uv sync

Configuration and running the MCP server

The server uses environment variables to configure the IoTDB connection and SQL dialect. You can run the server locally with the following configuration as a starting point.

{
  "mcpServers": {
    "iotdb": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
        "run",
        "server.py"
      ],
      "env": {
        "IOTDB_HOST": "127.0.0.1",
        "IOTDB_PORT": "6667",
        "IOTDB_USER": "root",
        "IOTDB_PASSWORD": "root",
        "IOTDB_DATABASE": "test",
        "IOTDB_SQL_DIALECT": "table",
        "IOTDB_EXPORT_PATH": "/path/to/export/folder"
      }
    }
  }
}

Claude Desktop Integration

If you use Claude Desktop to manage MCP servers, add a configuration entry that points to the local MCP server process. The example below shows how to launch the server from a local directory using uv and to set IoTDB connection details.

{
  "mcpServers": {
    "iotdb": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
        "run",
        "server.py"
      ],
      "env": {
        "IOTDB_HOST": "127.0.0.1",
        "IOTDB_PORT": "6667",
        "IOTDB_USER": "root",
        "IOTDB_PASSWORD": "root",
        "IOTDB_DATABASE": "test",
        "IOTDB_SQL_DIALECT": "table",
        "IOTDB_EXPORT_PATH": "/path/to/export/folder"
      }
    }
  }
}

Docker support

You can containerize the IoTDB MCP Server to simplify deployment and isolation. Build and run the image with the environment values shown.

# Build Docker image
docker build -t iotdb-mcp-server .

# Run container with IoTDB connection details
docker run -e IOTDB_HOST=192.168.1.100 -e IOTDB_PORT=6667 -e IOTDB_USER=root -e IOTDB_PASSWORD=root -e IOTDB_DATABASE=test iotdb-mcp-server

Notes and troubleshooting

The server supports exporting query results and uses a session pool with a fetch size to optimize performance. If you encounter connection issues, verify that IoTDB is reachable at the configured host and port, and confirm that the user credentials and database name are correct. Ensure the SQL dialect matches your query type (tree or table). Make sure environment variables are correctly exported in the shell or included in your runtime configuration.

Available tools

metadata_query

Execute SHOW/COUNT queries to read metadata from IoTDB using the Tree Model. Returns results as objects.

select_query

Execute SELECT queries to read data from IoTDB using the Tree Model. Supports aggregation and time-based functions.

export_query

Execute a query and export results to CSV or Excel using the Tree Model. Returns file info and a preview.

read_query

Execute SELECT queries to read data from IoTDB using the Table Model. Returns results as objects.

list_tables

List all tables in the IoTDB database for the Table Model.

describe_table

Describe the schema of a specific table in the Table Model.

export_table_query

Execute a query and export results to CSV or Excel using the Table Model. Returns file info and a preview.