Apache IoTDB MCP Server

What does “IoTDB” MCP Server do?

The Apache IoTDB MCP Server is an implementation of the Model Context Protocol (MCP) designed to provide seamless database interaction and business intelligence capabilities through IoTDB, a time-series database. By acting as a bridge, it enables AI assistants and clients to execute SQL queries against IoTDB, supporting data analysis and management tasks directly through natural language or programmatic LLM-driven workflows. Developers can use the MCP server to perform database queries, view schema information, and retrieve metadata, enhancing their ability to integrate IoTDB into AI-powered development environments for tasks such as querying time-series data and managing database schemas.

List of Prompts

The server doesn’t provide any prompts.

List of Resources

The server doesn’t expose any resources.

List of Tools

The IoTDB MCP Server offers different tools depending on the selected SQL dialect (“tree” or “table”).

Tree Model

• metadata_query
  • Executes SHOW/COUNT queries to retrieve metadata from the IoTDB database.
  • Input: query_sql (string) – The SHOW/COUNT SQL query to execute.
  • Output: Query results as an array of objects.
• select_query
  • Executes SELECT queries to read time-series data from the database.
  • Input: query_sql (string) – The SELECT SQL query to execute.
  • Output: Query results as an array of objects.

Table Model

Query Tools

• read_query
  • Executes SELECT queries to read data from the database.
  • Input: query (string) – The SELECT SQL query to execute.
  • Output: Query results as an array of objects.

Schema Tools

• list_tables
  • Retrieves a list of all tables in the database.
  • Input: None.
  • Output: Array of table names.
• describe-table
  • Provides schema information for a specific table.
  • Input: table_name (string) – Name of the table to describe.
  • Output: Array of column definitions with names and types.

Use Cases of this MCP Server

• Time-Series Database Management
  Easily query, browse, and manage large-scale time-series data stored in IoTDB directly from AI assistants or LLM-powered developer tools.
• Schema Exploration
  Retrieve and explore database schema, get lists of tables, and view table descriptions to understand and document database structure.
• Business Intelligence Integration
  Integrate IoTDB data into BI workflows with natural language querying and schema analysis, facilitating analytics and reporting.
• Automated Data Analytics
  Use the MCP server as a backend for automated data analysis pipelines, where LLMs generate and run SQL queries based on user intent.
• Metadata Inspection
  Run SHOW/COUNT queries to view database metadata, helping with monitoring, auditing, and database optimization tasks.

How to set it up

Windsurf

1. Ensure you have Python installed and the uv package manager.
2. Install or clone the IoTDB MCP Server repository.
3. Edit the Windsurf configuration file to add the IoTDB MCP Server.
4. Use the following JSON snippet in your config:

   {
     "mcpServers": {
       "iotdb": {
         "command": "uv",
         "args": [
           "--directory",
           "YOUR_REPO_PATH/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"
         }
       }
     }
   }
   

5. Save the configuration and restart Windsurf.
6. Verify the server is running and connected.

Claude

1. Install Python, uv, and IoTDB as prerequisites.
2. Clone the IoTDB MCP Server repository.
3. On MacOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, edit %APPDATA%/Claude/claude_desktop_config.json.
4. Add the MCP server entry:

   {
     "mcpServers": {
       "iotdb": {
         "command": "uv",
         "args": [
           "--directory",
           "YOUR_REPO_PATH/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"
         }
       }
     }
   }
   

5. Save changes and restart Claude Desktop.
6. Confirm the server is available in Claude.

Cursor

1. Make sure Python, uv, and IoTDB are installed.
2. Clone the MCP server repository.
3. Edit Cursor’s configuration to include the MCP server.
4. Use the following JSON:

   {
     "mcpServers": {
       "iotdb": {
         "command": "uv",
         "args": [
           "--directory",
           "YOUR_REPO_PATH/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"
         }
       }
     }
   }
   

5. Save the configuration and restart Cursor.
6. Ensure the MCP server is active and responsive.

Cline

1. Install necessary dependencies: Python, uv, and IoTDB.
2. Clone the Apache IoTDB MCP Server.
3. Open Cline’s configuration file.
4. Add the MCP server info as shown:

   {
     "mcpServers": {
       "iotdb": {
         "command": "uv",
         "args": [
           "--directory",
           "YOUR_REPO_PATH/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"
         }
       }
     }
   }
   

5. Save and restart Cline.
6. Check the MCP server integration.

Securing API Keys
API credentials such as IOTDB_USER and IOTDB_PASSWORD are managed via the env field in the configuration. Use environment variables to avoid hard-coding sensitive data. Example:

"env": {
  "IOTDB_HOST": "127.0.0.1",
  "IOTDB_PORT": "6667",
  "IOTDB_USER": "${IOTDB_USER}",
  "IOTDB_PASSWORD": "${IOTDB_PASSWORD}",
  "IOTDB_DATABASE": "test"
}

And set these environment variables in your system before starting the server.

How to use this MCP inside flows

Using MCP in FlowHunt

To integrate MCP servers into your FlowHunt workflow, start by adding the MCP component to your flow and connecting it to your AI agent:

Click on the MCP component to open the configuration panel. In the system MCP configuration section, insert your MCP server details using this JSON format:

{
  "iotdb": {
    "transport": "streamable_http",
    "url": "https://yourmcpserver.example/pathtothemcp/url"
  }
}

Once configured, the AI agent is now able to use this MCP as a tool with access to all its functions and capabilities. Remember to change “iotdb” to whatever the actual name of your MCP server is and replace the URL with your own MCP server URL.

Overview

Our opinion

The IoTDB MCP Server is a focused, minimal implementation providing essential database-interaction tools for IoTDB. It lacks advanced MCP features such as prompts, resources, roots, and sampling, but is well-suited for its specific use-case in time-series database access. Setup is well-documented for Claude Desktop; other integrations are inferred but standard. Overall, this is a niche but solid MCP server for database-centric workflows.

MCP Score