Apache IoTDB

by apache

12 stars

354 downloads

Not rated

GitHub Website

About

Connects to Apache IoTDB time-series databases for executing queries, listing tables, and describing schemas through a secure Python-based interface.

Details

Author: apache
Repository: apache/iotdb-mcp-server
GitHub stars: 12
Downloads: 354
License: Apache License 2.0
Categories: AI, Design, Developer Tools, Search, Database, Frontend, Infrastructure, Other

- Supports both Tree Model and Table Model SQL dialects
- Tools for metadata queries and data selection per model
- Export query results to CSV or Excel files
- Session pool with up to 100 concurrent connections
- Automatic connection retry and timeout management
- Docker support for containerized deployment

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Apache IoTDB

Command (node, npx, python, etc.) uv
Arguments
- Argument 1 --directory
- Argument 2 /Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server
- Argument 3 run
- Argument 4 server.py
Environment
- 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
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "%APPDATA%/Claude/claude_desktop_config.json",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "%APPDATA%/Claude/claude_desktop_config.json",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "%APPDATA%/Claude/claude_desktop_config.json",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "%APPDATA%/Claude/claude_desktop_config.json",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "%APPDATA%/Claude/claude_desktop_config.json",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

From the repository

IoTDB MCP Server supports the following configuration options, which can be set via environment variables or command-line arguments:

| Option | Environment Variable | Default Value | Description |
| ------------- | -------------------- | ------------- | -------------------------------- |
| --host | IOTDB_HOST | 127.0.0.1 | IoTDB host address |
| --port | IOTDB_PORT | 6667 | IoTDB port |
| --user | IOTDB_USER | root | IoTDB username |
| --password | IOTDB_PASSWORD | root | IoTDB password |
| --database | IOTDB_DATABASE | test | IoTDB database name |
| --sql-dialect | IOTDB_SQL_DIALECT | table | SQL dialect: tree or table |
| --export-path | IOTDB_EXPORT_PATH | /tmp | Path for exporting query results |

uv venv
source venv/bin/activate # or venv\Scripts\activate on Windows

uv sync
```

`metadata_query`

Execute SHOW/COUNT queries to read metadata from the database. Input: query_sql (string): The SHOW/COUNT SQL query to execute. Supported query types include SHOW DATABASES, SHOW TIMESERIES, COUNT TIMESERIES, etc. Returns: Query results as an array of objects.

`select_query`

Execute SELECT queries to read data from the database. Input: query_sql (string): The SELECT SQL query to execute (using TREE dialect). Returns: Query results as an array of objects.

`export_query`

Execute a query and export the results to a CSV or Excel file. Input: query_sql (string): The SQL query to execute; format (string): Export format, either 'csv' or 'excel'; filename (string): Optional filename for the exported file. Returns: Information about the exported file and a preview of the data.

`read_query`

Execute SELECT queries to read data from the database. Input: query_sql (string): The SELECT SQL query to execute (using TABLE dialect). Returns: Query results as an array of objects.

`list_tables`

Get a list of all tables in the database. No input required. Returns: Array of table names.

`describe_table`

View schema information for a specific table. Input: table_name (string): Name of table to describe. Returns: Array of column definitions with names and types.

`export_table_query`

The server offers different tools for IoTDB Tree Model and Table Model. You can choose between them by setting the "IOTDB_SQL_DIALECT" configuration to either "tree" or "table".

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "apache iotdb": {
            "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"
            },
            "args": [
                "--directory",
                "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

Linux

{
    "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"
    },
    "args": [
        "--directory",
        "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
        "run",
        "server.py"
    ],
    "command": "uv"
}

Macos

{
    "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"
    },
    "args": [
        "--directory",
        "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
        "run",
        "server.py"
    ],
    "command": "uv"
}

Windows

{
    "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"
    },
    "args": [
        "--directory",
        "%APPDATA%/Claude/claude_desktop_config.json",
        "run",
        "server.py"
    ],
    "command": "uv"
}

IoTDB MCP Server

English | 中文

Overview

A Model Context Protocol (MCP) server implementation that provides database interaction and business intelligence capabilities through IoTDB. This server enables running SQL queries and interacting with IoTDB using different SQL dialects (Tree Model and Table Model).

Components

Resources

The server doesn't expose any resources.

Prompts

The server doesn't provide any prompts.

Tools

The server offers different tools for IoTDB Tree Model and Table Model. You can choose between them by setting the "IOTDB_SQL_DIALECT" configuration to either "tree" or "table".

Tree Model

- metadata_query
- Execute SHOW/COUNT queries to read metadata from the database
- Input:
- query_sql (string): The SHOW/COUNT SQL query to execute
- Supported query types:
- SHOW DATABASES [path]
- SHOW TIMESERIES [path]
- SHOW CHILD PATHS [path]
- SHOW CHILD NODES [path]
- SHOW DEVICES [path]
- COUNT TIMESERIES [path]
- COUNT NODES [path]
- COUNT DEVICES [path]
- Returns: Query results as array of objects
- select_query
- Execute SELECT queries to read data from the database
- Input:
- query_sql (string): The SELECT SQL query to execute (using TREE dialect, time using ISO 8601 format, e.g. 2017-11-01T00:08:00.000)
- Supported functions:
- SUM, COUNT, MAX_VALUE, MIN_VALUE, AVG, VARIANCE, MAX_TIME, MIN_TIME, etc.
- Returns: Query results as array of objects
- export_query
- Execute a query and export the results to a CSV or Excel file
- Input:
- query_sql (string): The SQL query to execute (using TREE dialect)
- format (string): Export format, either "csv" or "excel" (default: "csv")
- filename (string): Optional filename for the exported file. If not provided, a unique filename will be generated.
- Returns: Information about the exported file and a preview of the data (max 10 rows)

Table Model

Query Tools

- read_query
- Execute SELECT queries to read data from the database
- Input:
- query_sql (string): The SELECT SQL query to execute (using TABLE dialect, time using ISO 8601 format, e.g. 2017-11-01T00:08:00.000)
- Returns: Query results as array of objects

Schema Tools

- list_tables

- Get a list of all tables in the database
- No input required
- Returns: Array of table names

- describe_table

- View schema information for a specific table
- Input:
- table_name (string): Name of table to describe
- Returns: Array of column definitions with names and types

- export_table_query
- Execute a query and export the results to a CSV or Excel file
- Input:
- query_sql (string): The SQL query to execute (using TABLE dialect)
- format (string): Export format, either "csv" or "excel" (default: "csv")
- filename (string): Optional filename for the exported file. If not provided, a unique filename will be generated.
- Returns: Information about the exported file and a preview of the data (max 10 rows)

Configuration Options

IoTDB MCP Server supports the following configuration options, which can be set via environment variables or command-line arguments:

Performance Optimizations

IoTDB MCP Server includes the following performance optimization features:

1. Session Pool Management: Uses optimized session pool configurations, supporting up to 100 concurrent sessions
2. Optimized Fetch Size: For queries, a fetch size of 1024 is set
3. Connection Retry: Configured automatic retry mechanism for connection failures
4. Timeout Management: Session wait timeout set to 5000 milliseconds for improved reliability
5. Export Functionality: Support for exporting query results to CSV or Excel formats

Prerequisites

- Python environment
- uv package manager
- IoTDB installation
- MCP server dependencies

Development

# Clone the repository
git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb-mcp-server
Create virtual environment
uv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
Install development dependencies
uv sync

Claude Desktop Integration

Configure the MCP server in Claude Desktop's configuration file:

macOS

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

metadata_query

select_query

export_query

read_query

list_tables

describe_table

export_table_query

Claude Desktop / Cursor

Linux

Macos

Windows

IoTDB MCP Server

Overview

Components

Resources

Prompts

Tools

Tree Model

Table Model

Query Tools

Schema Tools

Configuration Options

Performance Optimizations

Prerequisites

Development

Create virtual environment

Install development dependencies

Claude Desktop Integration

macOS

Install

More like this

Sentry

Github

Git

GitLab

Context 7

1Panel

`metadata_query`

`select_query`

`export_query`

`read_query`

`list_tables`

`describe_table`

`export_table_query`