IoTDB MCP Server
Official Apache IoTDB MCP server: SQL over time series in tree and table models, with CSV and Excel export
Install
{
"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": "",
"IOTDB_DATABASE": "test",
"IOTDB_SQL_DIALECT": "table",
"IOTDB_EXPORT_PATH": "/path/to/export/folder"
}
}
}
}Clone the repo and run uv sync first. Replace the --directory path with yours.
This is third-party code. Review the repository files before installing.
What it does
The server gives the agent access to the Apache IoTDB time series database. In the table dialect the agent lists tables, describes their schema and runs SELECT. In the tree dialect it reads metadata with SHOW and COUNT, runs queries and read-only query batches with paged results. Results can be exported to CSV or Excel. There are tools for calling user-defined functions and AINode model inference, and before modifying queries the server reports required permissions and risk level.
Who it is for. For data engineers and IoT developers storing telemetry in Apache IoTDB.
Good fit when
- You want to ask the agent about sensor readings over a period without writing SQL
- You need to explore the structure of an unfamiliar IoTDB database
- You need to export query results to Excel for a report
Not a fit when
- Your data is not in IoTDB
- You need hard blocking of modifying queries but will not configure strict mode
Example request
List the tables in the database and the average temperature per device for yesterdayLimitations
The README has no one-command package: clone the repo and run it with uv, or build a Docker image. A reachable IoTDB instance is required. Permission checks are advisory by default; hard blocking needs TIMESEEK_MCP_PERMISSION_ENFORCEMENT=strict. The tree or table dialect is chosen at startup.
How to disable. Remove the iotdb block from claude_desktop_config.json or stop the iotdb-mcp-server container.
MCP
- Transport
- stdio
- Authentication
- API key
| Environment variables | |
|---|---|
| IOTDB_HOST | IoTDB host, 127.0.0.1 by default. |
| IOTDB_PORT | IoTDB port, 6667 by default. |
| IOTDB_USER | Username, root by default. |
| IOTDB_PASSWORD secret | IoTDB user password. |
| IOTDB_DATABASE | Database for the table dialect. |
| IOTDB_SQL_DIALECT | Dialect: tree or table, table by default. |
| IOTDB_EXPORT_PATH | Folder for CSV and Excel exports. |
Security check
- Runs SQL against the database, including potentially modifying queries
- Keeps the database password in config
README in short
The README lists tools for the tree and table models, UDF and inference tools, and the permission model. Connection settings come from arguments or environment variables. It gives a Claude Desktop config via uv, Docker build and run commands, and covers session pooling, connection retries and error handling. Apache 2.0 licensed.
FAQ
How do tree and table dialects differ?
Tree queries address root... paths, table queries address tables and columns in the current database. The tool set depends on the chosen dialect.
Can the agent modify data?
The server reports risk for modifying queries and leaves approval to the host agent. Enable strict mode for hard blocking.
Related
166 skills for scientific work: bioinformatics, cheminformatics, clinical data, geospatial analysis and 100+ databases
Google's open-source MCP server for databases: ready tools for Postgres, MySQL, BigQuery, Spanner and more, plus custom tools in tools.yaml
Official Hugging Face skills: Hub operations via the hf CLI, datasets, model training, Spaces, evals and deployment
A token-lean MCP server for PostgreSQL, MySQL, MariaDB, SQL Server and SQLite with a read-only mode