Unleashing the Power of IoTDB with the Model Context Protocol (MCP)

This document details the implementation of an MCP server that bridges the gap between Large Language Models (LLMs) and the Apache IoTDB database, enabling sophisticated data interaction and business intelligence capabilities. By leveraging the Model Context Protocol, this server provides a standardized interface for LLMs to access and utilize the wealth of data stored within IoTDB.

Core Components

This MCP server implementation focuses on providing essential database interaction capabilities. It exposes a suite of tools designed to empower LLMs with the ability to query, understand, and leverage IoTDB data.

Key Tools

The server offers the following tools:

• read_query (Query Tool):

  • Functionality: Executes arbitrary SELECT SQL queries against the IoTDB database. This allows LLMs to retrieve specific data based on complex criteria.
  • Input:
    • query (string): A valid SELECT SQL query string.
  • Output:
    • An array of objects, where each object represents a row in the query result set. Each object's keys correspond to the selected columns.

• list_tables (Schema Tool):

  • Functionality: Retrieves a comprehensive list of all tables currently available within the connected IoTDB database. This allows LLMs to dynamically discover the available data sources.
  • Input: None
  • Output:
    • An array of strings, where each string represents the name of a table in the database.

• describe_table (Schema Tool):

  • Functionality: Provides detailed schema information for a specified table, including column names and their corresponding data types. This enables LLMs to understand the structure and content of individual tables.
  • Input:
    • table_name (string): The name of the table for which schema information is requested.
  • Output:
    • An array of objects, where each object represents a column definition. Each object contains the following keys:
      • name (string): The name of the column.
      • type (string): The data type of the column.

Integration with Claude Desktop

This section outlines the steps required to integrate the IoTDB MCP server with the Claude Desktop application, enabling seamless interaction between Claude and your IoTDB data.

Prerequisites

Before proceeding with the integration, ensure that the following prerequisites are met:

• Python Environment: A working Python environment with the uv package manager installed. uv is recommended for managing dependencies and creating isolated environments.
• IoTDB Installation: A properly configured and running instance of Apache IoTDB.
• MCP Server Dependencies: All necessary dependencies for the IoTDB MCP server are installed (see Development section below).

Development Setup

Follow these steps to set up the development environment for the IoTDB MCP server:

# Clone the repository
git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb_mcp_server

# Create a virtual environment using uv
uv venv

# Activate the virtual environment
source venv/bin/activate  # On Linux/macOS
# venv\Scripts\activate  # On Windows

# Install development dependencies
uv sync

Claude Desktop Configuration

To configure Claude Desktop to use the IoTDB MCP server, you need to modify the claude_desktop_config.json file. The location of this file varies depending on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Add a new entry to the mcpServers section of the configuration file, specifying the command and arguments required to start the IoTDB MCP server.

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

Important Notes:

• Replace YOUR_REPO_PATH with the actual path to the cloned repository.
• The command field should point to the uv executable. You may need to provide the full path to the executable. You can find the full path by running which uv on macOS/Linux or where uv on Windows.
• The env section allows you to configure the connection parameters for your IoTDB instance. Adjust the IOTDB_HOST, IOTDB_PORT, IOTDB_USER, IOTDB_PASSWORD, and IOTDB_DATABASE values to match your IoTDB setup.

By following these steps, you can seamlessly integrate the IoTDB MCP server with Claude Desktop, unlocking the potential of LLMs to interact with and derive insights from your IoTDB data.