by apache
Provides SQL query execution and business‑intelligence capabilities over IoTDB, supporting both Tree and Table dialects, metadata retrieval, data selection, and export of results to CSV or Excel formats.
Enables interaction with an IoTDB instance via a Model Context Protocol (MCP) server. Users can run metadata queries, data SELECT statements, and export query results while choosing between the Tree or Table SQL dialects.
git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb-mcp-server
uv venv
source venv/bin/activate # Windows: venv\Scripts\activate
uv sync
IOTDB_HOST, IOTDB_PORT, IOTDB_USER, IOTDB_PASSWORD, IOTDB_DATABASE, IOTDB_SQL_DIALECT, IOTDB_EXPORT_PATH).uv run src/iotdb_mcp_server/server.py
Adjust the command path if the server script resides elsewhere.metadata_query) for SHOW/COUNT operations on databases, timeseries, devices, etc.select_query, read_query) supporting standard aggregation functions.export_query, export_table_query) to CSV or Excel with preview of up to 10 rows.list_tables, describe_table).Q: How do I switch between Tree and Table dialects?
A: Set the environment variable IOTDB_SQL_DIALECT to tree or table (default is table).
Q: Which time format is required for SELECT queries?
A: ISO 8601 format, e.g., 2017-11-01T00:08:00.000.
Q: Can I change the export directory?
A: Yes, modify IOTDB_EXPORT_PATH to point to the desired folder.
Q: What Python version is needed?
A: Any version supported by the uv package manager (typically Python 3.8+).
Q: How many concurrent sessions are supported? A: The server’s session pool is configured for up to 100 concurrent sessions.
Q: How do I run the server inside a Docker container?
A: Build the image with docker build -t iotdb-mcp-server . and run it using docker run -e IOTDB_HOST=... -e IOTDB_PORT=... iotdb-mcp-server.
English | 中文
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).
The server doesn't expose any resources.
The server doesn't provide any prompts.
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".
metadata_query
query_sql (string): The SHOW/COUNT SQL query to executeselect_query
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)export_query
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.Query Tools
read_query
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)Schema Tools
list_tables
describe_table
table_name (string): Name of table to describeexport_table_query
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.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 |
IoTDB MCP Server includes the following performance optimization features:
uv package manager# 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
Configure the MCP server in Claude Desktop's configuration file:
Location: ~/Library/Application Support/Claude/claude_desktop_config.json
Location: %APPDATA%/Claude/claude_desktop_config.json
You may need to put the full path to the uv executable in the command field. You can get this by running which uv on MacOS/Linux or where uv on Windows.
Add the following configuration to Claude Desktop's configuration file:
{
"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"
}
}
}
}
Note: Make sure to replace the
--directoryparameter's path with your actual repository clone path.
IoTDB MCP Server includes comprehensive error handling and logging capabilities:
You can build a container image for the IoTDB MCP Server using the Dockerfile in the project root:
# Build Docker image
docker build -t iotdb-mcp-server .
# Run container
docker run -e IOTDB_HOST=<your-iotdb-host> -e IOTDB_PORT=<your-iotdb-port> -e IOTDB_USER=<your-iotdb-user> -e IOTDB_PASSWORD=<your-iotdb-password> iotdb-mcp-server
Please log in to share your review and rating for this MCP.
{
"mcpServers": {
"iotdb-mcp-server": {
"command": "uv",
"args": [
"run",
"src/iotdb_mcp_server/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": "/tmp"
}
}
}
}claude mcp add iotdb-mcp-server uv run src/iotdb_mcp_server/server.pyExplore related MCPs that share similar capabilities and solve comparable challenges
by googleapis
An MCP server that streamlines database tool development by handling connection pooling, authentication, observability, and secure access, allowing agents to interact with databases via natural language.
by bytebase
Provides a universal gateway that lets MCP‑compatible clients explore and query MySQL, PostgreSQL, SQL Server, MariaDB, and SQLite databases through a single standardized interface.
by designcomputer
Enables secure interaction with MySQL databases via the Model Context Protocol, allowing AI applications to list tables, read contents, and execute queries safely.
by benborla
Provides read‑only access to MySQL databases for large language models, allowing schema inspection and safe execution of SQL queries.
by neo4j-contrib
Enables natural‑language interaction with Neo4j databases, allowing large language models to query, modify, and manage graph data through multiple transport modes.
by mongodb-js
Provides a Model Context Protocol server that enables interaction with MongoDB databases and MongoDB Atlas clusters through a unified API.
by ClickHouse
Enables AI assistants to run read‑only ClickHouse queries, list databases and tables, and execute embedded chDB queries through an MCP interface.
by neondatabase
Interact with Neon Postgres databases using natural language commands through the Model Context Protocol, enabling conversational database creation, migration, and query execution.
by motherduckdb
Enables SQL analytics on DuckDB and MotherDuck databases via a Model Context Protocol server, allowing AI assistants and IDEs to query data directly.