Apache IoTDB
Apache IoTDB MCP Server
What is Apache IoTDB?
Apache IoTDB is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to apache iotdb mcp server
Apache IoTDB MCP Server
This server falls under the Databases category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Apache IoTDB MCP Server
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx iotdbConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Apache IoTDB
The Apache IoTDB MCP Server provides AI assistants with direct read and query access to Apache IoTDB, a purpose-built time series database for industrial IoT data. It exposes tools for listing tables, describing schemas, running SQL SELECT queries, and exporting results to CSV or Excel — across both the tree-model and table-model query dialects that IoTDB supports. Engineers and data analysts use it to ask natural-language questions about sensor streams, equipment telemetry, and time-stamped measurements stored in IoTDB, without writing SQL by hand. It connects to a running IoTDB instance over the standard Thrift session protocol and requires only a Python environment to run.
Prerequisites
- Python 3.10 or newer with uv package manager (pip install uv)
- A running Apache IoTDB instance (version 1.x or newer) accessible on the network
- IoTDB connection credentials: host, port (default 6667), username, and password
- An MCP-compatible client such as Claude Desktop or Cursor
- Optional: Docker for running IoTDB or the MCP server in containers
Clone the IoTDB MCP Server repository
Clone the official Apache IoTDB MCP Server source from GitHub and enter the project directory.
git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb-mcp-serverCreate a Python virtual environment and install dependencies
Use uv to create an isolated environment and install all required Python packages.
uv venv
source venv/bin/activate # Windows: venv\Scripts\activate
uv syncConfigure connection environment variables
Set the IoTDB connection parameters as environment variables. IOTDB_SQL_DIALECT should be 'table' for IoTDB 1.x table model or 'tree' for the older tree model.
export IOTDB_HOST=127.0.0.1
export IOTDB_PORT=6667
export IOTDB_USER=root
export IOTDB_PASSWORD=root
export IOTDB_DATABASE=test
export IOTDB_SQL_DIALECT=table
export IOTDB_EXPORT_PATH=/tmpTest the server locally
Run the server directly to confirm it connects to your IoTDB instance without errors before wiring it into a client.
python src/iotdb_mcp_server/server.pyAdd to Claude Desktop configuration
Open your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the IoTDB server block.
{
"mcpServers": {
"iotdb": {
"command": "uv",
"args": [
"--directory",
"/path/to/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"
}
}
}
}Apache IoTDB Examples
Client configuration (Claude Desktop)
Full configuration block for Claude Desktop, using uv to launch the IoTDB MCP server with explicit connection environment variables.
{
"mcpServers": {
"iotdb": {
"command": "uv",
"args": [
"--directory",
"/path/to/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": "/tmp"
}
}
}
}Prompts to try
Natural-language queries you can ask your AI assistant once the IoTDB MCP Server is connected.
- "List all tables in the test database."
- "Describe the schema of the temperature_readings table."
- "Show me the last 100 temperature readings from sensor_001 ordered by time descending."
- "Export all readings from device_002 between 2024-01-01 and 2024-01-31 to a CSV file."
- "What is the average vibration level for pump_station_A over the last 7 days?"Troubleshooting Apache IoTDB
Connection refused error when starting the server.
Verify that your IoTDB instance is running and listening on the configured IOTDB_HOST and IOTDB_PORT (default 6667). Check firewall rules and confirm with 'nc -zv 127.0.0.1 6667'. The IoTDB service must be started before the MCP server.
Query returns 'Table not found' or empty results.
Ensure IOTDB_DATABASE matches the database name in your IoTDB instance. Use the list_tables tool first to see which tables exist. If using tree-model data, set IOTDB_SQL_DIALECT=tree and use the metadata_query and select_query tools instead of the table-model equivalents.
uv sync fails or dependencies cannot be resolved.
Upgrade uv to the latest version with 'pip install --upgrade uv' and retry. Ensure you have activated the virtual environment created by 'uv venv' before running 'uv sync'.
Frequently Asked Questions about Apache IoTDB
What is Apache IoTDB?
Apache IoTDB is a Model Context Protocol (MCP) server that apache iotdb mcp server It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Apache IoTDB?
Follow the installation instructions on the Apache IoTDB GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Apache IoTDB?
Apache IoTDB works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Apache IoTDB free to use?
Yes, Apache IoTDB is open source and available under the Apache-2.0 license. You can use it freely in both personal and commercial projects.
Apache IoTDB Alternatives — Similar Databases Servers
Looking for alternatives to Apache IoTDB? Here are other popular databases servers you can use with Claude, Cursor, and VS Code.
Excelize
★ 20.6kGo language library for reading and writing Microsoft Excel™ (XLAM / XLSM / XLSX / XLTM / XLTX) spreadsheets
MCP Toolbox for Databases
★ 15.3kOpen source MCP server specializing in easy, fast, and secure tools for Databases.
DBHub
★ 2.8kA universal database gateway MCP server that enables AI assistants to connect to and query multiple databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite) with support for schema exploration, SQL execution, and secure connections via SSH tunnels.
Tabularis
★ 2.1kA lightweight, cross-platform database client for developers. Supports MySQL, PostgreSQL and SQLite. Hackable with plugins. Built for speed, security, and aesthetics.
Postgres AI Guide
★ 1.7kMCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.
Anyquery
★ 1.7k🏎️ 🏠 ☁️ - Query more than 40 apps with one binary using SQL. It can also connect to your PostgreSQL, MySQL, or SQLite compatible database. Local-first and private by design.
Browse More Databases MCP Servers
Explore all databases servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Apache IoTDB in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Apache IoTDB?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.