Iotdb MCP Server

🚀 IoTDB MCP Server

A Model Context Protocol (MCP) server implementation that provides database interaction and business intelligence capabilities through IoTDB. The server supports running SQL queries.

🚀 Quick Start

Prerequisites

• Python with the 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 a virtual environment
uv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install development dependencies
uv sync

Configure the MCP server in the Claude Desktop configuration file:

MacOS

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

Location: %APPDATA%/Claude/claude_desktop_config.json

⚠️ Important Note

You may need to put the full path of the uv executable in the command field. You can obtain it by running which uv on MacOS/Linux or where uv on Windows.

{
  "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"
      }
    }
  }
}

✨ Features

Resources

The server does not expose any resources.

Tips

The server does not provide any tips.

Tools

The server provides different tools for the IoTDB tree model and table model. You can select them by setting the “IOTDB_SQL_DIALECT” configuration to “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.
  • Return: The 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.
  • Return: The query results as an array of objects.

Table Model

Query Tools

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

Schema Tools

• list_tables

  • Get a list of all tables in the database.
  • No input required.
  • Return: An array of table names.

• describe-table

  • View the schema information of a specific table.
  • Input:
    • table_name (string): The name of the table to describe.
  • Return: An array of column definitions containing names and types.