You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by ja...@apache.org on 2025/04/02 07:55:18 UTC
(iotdb-mcp-server) 01/01: Support mcp server for IoTDB
This is an automated email from the ASF dual-hosted git repository.
jackietien pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-mcp-server.git
commit be3bcaa64e9e11fc9c883f8670d1e3014bde6139
Author: JackieTien97 <ja...@gmail.com>
AuthorDate: Wed Apr 2 15:54:50 2025 +0800
Support mcp server for IoTDB
---
.gitignore | 23 ++++++++
README.md | 95 ++++++++++++++++++++++++++++++++
pyproject.toml | 31 +++++++++++
src/iotdb_mcp_server/__init__.py | 16 ++++++
src/iotdb_mcp_server/config.py | 86 +++++++++++++++++++++++++++++
src/iotdb_mcp_server/server.py | 113 +++++++++++++++++++++++++++++++++++++++
6 files changed, 364 insertions(+)
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..d53d616
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,23 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+Lib/
+Scripts/
+
+# Development environment
+.python-version
+uv.lock
+
+# IDE settings (optional)
+.vscode/
+.idea/
+
+# Distribution directories
+*.dist-info/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1ab9198
--- /dev/null
+++ b/README.md
@@ -0,0 +1,95 @@
+# IoTDB MCP Server
+
+## Overview
+A Model Context Protocol (MCP) server implementation that provides database interaction and business intelligence capabilities through IoTDB. This server enables running SQL queries.
+
+## Components
+
+### Resources
+The server doesn't expose any resources.
+
+### Prompts
+The server doesn't provide any prompts.
+
+### Tools
+The server offers three core tools:
+
+#### Query Tools
+- `read_query`
+ - Execute SELECT queries to read data from the database
+ - Input:
+ - `query` (string): The SELECT SQL query to execute
+ - Returns: Query results as array of objects
+
+
+#### Schema Tools
+- `list_tables`
+ - Get a list of all tables in the database
+ - No input required
+ - Returns: Array of table names
+
+- `describe-table`
+ - View schema information for a specific table
+ - Input:
+ - `table_name` (string): Name of table to describe
+ - Returns: Array of column definitions with names and types
+
+
+
+## Claude Desktop Integration
+
+## Prerequisites
+- Python with `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 virtual environment
+uv venv
+source venv/bin/activate # or `venv\Scripts\activate` on Windows
+
+# Install development dependencies
+uv sync
+```
+
+
+
+Configure the MCP server in Claude Desktop's configuration file:
+
+#### MacOS
+
+Location: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+#### Windows
+
+Location: `%APPDATA%/Claude/claude_desktop_config.json`
+
+
+```json
+{
+ "mcpServers": {
+ "iotdb": {
+ "command": "uv",
+ "args": [
+ "--directory",
+ "parent_of_servers_repo/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"
+ }
+ }
+ }
+}
+```
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..88f5b46
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,31 @@
+[project]
+name = "iotdb-mcp-server"
+packages = [{ include = "src/iotdb_mcp_server" }]
+version = "0.1.0"
+description = "A Model Context Protocol (MCP) server that enables secure interaction with GreptimeDB databases. This server allows AI assistants to list tables, read data, and execute SQL queries through a controlled interface, making database exploration and analysis safer and more structured."
+requires-python = ">=3.11"
+dependencies = [
+ "mcp>=1.0.0",
+ "apache-iotdb>=2.0.1b0"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+exclude = [
+ "venv",
+ ".git",
+ ".gitignore"
+]
+
+[tool.uv]
+dev-dependencies = [
+ "pyright",
+ "black",
+ "flake8",
+]
+
+[project.scripts]
+iotdb-mcp-server = "iotdb_mcp_server:main"
\ No newline at end of file
diff --git a/src/iotdb_mcp_server/__init__.py b/src/iotdb_mcp_server/__init__.py
new file mode 100644
index 0000000..66d74c4
--- /dev/null
+++ b/src/iotdb_mcp_server/__init__.py
@@ -0,0 +1,16 @@
+from iotdb_mcp_server.config import Config
+import sys
+
+if not "-m" in sys.argv:
+ from . import server
+import asyncio
+
+
+def main():
+ """Main entry point for the package."""
+ _config = Config.from_env_arguments()
+ asyncio.run(server.main(_config))
+
+
+# Expose important items at package level
+__all__ = ["main", "server"]
diff --git a/src/iotdb_mcp_server/config.py b/src/iotdb_mcp_server/config.py
new file mode 100644
index 0000000..40ddda3
--- /dev/null
+++ b/src/iotdb_mcp_server/config.py
@@ -0,0 +1,86 @@
+import argparse
+from dataclasses import dataclass
+import os
+
+
+@dataclass
+class Config:
+ """
+ Configuration for the IoTDB mcp server.
+ """
+
+ host: str
+ """
+ IoTDB host
+ """
+
+ port: int
+ """
+ IoTDB port
+ """
+
+ user: str
+ """
+ IoTDB username
+ """
+
+ password: str
+ """
+ IoTDB password
+ """
+
+ database: str
+ """
+ IoTDB database name
+ """
+
+ @staticmethod
+ def from_env_arguments() -> "Config":
+ """
+ Parse command line arguments.
+ """
+ parser = argparse.ArgumentParser(description="IoTDB MCP Server")
+
+ parser.add_argument(
+ "--host",
+ type=str,
+ help="IoTDB host",
+ default=os.getenv("IOTDB_HOST", "127.0.0.1"),
+ )
+
+ parser.add_argument(
+ "--port",
+ type=int,
+ help="IoTDB MySQL protocol port",
+ default=os.getenv("IOTDB_PORT", 6667),
+ )
+
+ parser.add_argument(
+ "--database",
+ type=str,
+ help="IoTDB connect database name",
+ default=os.getenv("IOTDB_DATABASE", "test"),
+ )
+
+ parser.add_argument(
+ "--user",
+ type=str,
+ help="IoTDB username",
+ default=os.getenv("IOTDB_USER", "root"),
+ )
+
+ parser.add_argument(
+ "--password",
+ type=str,
+ help="IoTDB password",
+ default=os.getenv("IOTDB_PASSWORD", "root"),
+ )
+
+ args = parser.parse_args()
+ return Config(
+ host=args.host,
+ port=args.port,
+ database=args.database,
+ user=args.user,
+ password=args.password,
+ )
diff --git a/src/iotdb_mcp_server/server.py b/src/iotdb_mcp_server/server.py
new file mode 100644
index 0000000..7f26d21
--- /dev/null
+++ b/src/iotdb_mcp_server/server.py
@@ -0,0 +1,113 @@
+import logging
+
+from iotdb.table_session import TableSession
+from iotdb.table_session_pool import TableSessionPool, TableSessionPoolConfig
+from iotdb.utils.SessionDataSet import SessionDataSet
+from mcp.server.fastmcp import FastMCP
+from mcp.types import (
+ TextContent,
+)
+
+from iotdb_mcp_server.config import Config
+
+# Initialize FastMCP server
+mcp = FastMCP("iotdb_mcp_server")
+
+# Configure logging
+logging.basicConfig(
+ level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+
+logger = logging.getLogger("iotdb_mcp_server")
+
+config = Config.from_env_arguments()
+
+db_config = {
+ "host": config.host,
+ "port": config.port,
+ "user": config.user,
+ "password": config.password,
+ "database": config.database,
+}
+
+logger.info(f"IoTDB Config: {db_config}")
+
+session_pool_config = TableSessionPoolConfig(
+ node_urls=[str(config.host) + ":" + str(config.port)],
+ username=config.user,
+ password=config.password,
+ database=None if len(config.database) == 0 else config.database,
+)
+
+session_pool = TableSessionPool(session_pool_config)
+
+
+@mcp.tool()
+async def read_query(query_sql: str) -> list[TextContent]:
+ """Execute a SELECT query on the IoTDB. Please use table sql_dialect when generating SQL queries.
+
+ Args:
+ query_sql: The SQL query to execute (using TABLE dialect)
+ """
+ table_session = session_pool.get_session()
+ res = table_session.execute_query_statement(query_sql)
+
+ stmt = query_sql.strip().upper()
+ # Regular SELECT queries
+ if (
+ stmt.startswith("SELECT")
+ or stmt.startswith("DESCRIBE")
+ or stmt.startswith("SHOW")
+ ):
+ return prepare_res(res, table_session)
+ # Non-SELECT queries
+ else:
+ raise ValueError("Only SELECT queries are allowed for read_query")
+
+
+@mcp.tool()
+async def list_tables() -> list[TextContent]:
+ """List all tables in the IoTDB database."""
+ table_session = session_pool.get_session()
+ res = table_session.execute_query_statement("SHOW TABLES")
+
+ result = ["Tables_in_" + db_config["database"]] # Header
+ while res.has_next():
+ result.append(str(res.next().get_fields()[0]))
+ table_session.close()
+ return [TextContent(type="text", text="\n".join(result))]
+
+
+@mcp.tool()
+async def describe_table(table_name: str) -> list[TextContent]:
+ """Get the schema information for a specific table
+ Args:
+ table_name: name of the table to describe
+ """
+ table_session = session_pool.get_session()
+ res = table_session.execute_query_statement("DESC " + table_name)
+
+ return prepare_res(res, table_session)
+
+
+def prepare_res(
+ _res: SessionDataSet, _table_session: TableSession
+) -> list[TextContent]:
+ columns = _res.get_column_names()
+ result = []
+ while _res.has_next():
+ row = _res.next().get_fields()
+ result.append(",".join(map(str, row)))
+ _table_session.close()
+ return [
+ TextContent(
+ type="text",
+ text="\n".join([",".join(columns)] + result),
+ )
+ ]
+
+
+if __name__ == "__main__":
+ logger.info("iotdb_mcp_server running with stdio transport")
+ # Initialize and run the server
+ mcp.run(transport="stdio")