TDengine Query MCP Server

TDengine クエリ MCP サーバー

AI アシスタント向けに読み取り専用の TDengine データベースクエリを提供する Model Context Protocol（MCP）サーバーです。AI 搭載ツールから直接クエリを実行し、データベース構造を調べ、データを分析できます。

対応 AI ツール

この MCP サーバーは、以下を含む Model Context Protocol 対応のあらゆるツールで使用できます。

• Cursor IDE：.cursor/mcp.json で設定します
• Anthropic Claude：互換性のある MCP クライアントで使用します
• その他の MCP 対応 AI アシスタント：各ツールの MCP 設定手順に従ってください

機能と制限事項

できること

• ✅ 読み取り専用の TDengine クエリ（SELECT、SHOW、DESCRIBE のみ）を実行します
• ✅ データベース／スーパーテーブルの情報とメタデータを提供します
• ✅ 利用可能なデータベースとスーパーテーブルを一覧表示します

できないこと

• ❌ 書き込み操作（INSERT、UPDATE、DELETE、CREATE、ALTER など）を実行します
• ❌ データベース設計やスキーマ生成機能を提供します
• ❌ 完全なデータベース管理ツールとして機能します

このツールは、読み取り専用クエリによるデータの調査と探索専用に設計されています。データベース管理、スキーマ管理、データ変更を目的としたものではありません。

使用方法

ソースコードから実行する

この MCP サーバーの使用方法として推奨されるのは、インストールせずに uv で直接実行する方法です。以下の例では、Claude Desktop と Cursor の両方でこの方法を使って設定しています。

リポジトリをクローンする場合：

git clone https://github.com/Abeautifulsnow/tdengine-mcp.git
cd tdengine-mcp

その後、サーバーを直接実行できます。

uv run src/tdengine_mcp_server -th 192.100.8.22 -db log -ll debug

または、src/tdengine_mcp_server/ ディレクトリにある .env ファイルを変更して環境変数を設定し、次のコマンドでサーバーを実行できます。

uv run src/tdengine_mcp_server

重要：.env ファイルはコマンドライン引数よりも優先されます。

pip コマンドで PyPI からインストールする

# Install globally with pip
pip install tdengine_mcp_server

続いて、次のコマンドを実行します。

python -m tdengine_mcp_server -h

uvx コマンドでインストールする

uvx tdengine-mcp-server -h

npx コマンドで smithery からインストールする

npx -y @smithery/cli@latest install @Abeautifulsnow/tdengine-mcp --client cursor --config '"{}"'

--client オプションの後に、クライアントを claude、windsurf などに変更できます。こちらも参照してください：smithery/tdengine-mcp-server

設定オプション

.env ファイル

環境変数	説明	デフォルト
LOG_LEVEL	ログレベルを設定します（DEBUG、INFO、WARN、ERROR）	INFO
TDENGINE_HOST	環境のデータベースホスト	localhost
TDENGINE_PORT	データベースポート	6041
TDENGINE_USERNAME	データベースのユーザー名	root
TDENGINE_PASSWORD	データベースのパスワード	taosdata
TDENGINE_DATABASE	データベース名	log
TDENGINE_TIMEOUT	接続タイムアウトを秒単位で設定します	30
TRANSPORT	使用するトランスポートを指定します	stdio

CLI の使用方法

$ python3 -m tdengine_mcp_server -h

usage: __main__.py [-h] [-th TAOS_HOST] [-tp TAOS_PORT] [-tu TAOS_USERNAME] [-pwd TAOS_PASSWORD] [-db TAOS_DATABASE] [-to TAOS_TIMEOUT] [-ll LOG_LEVEL]

TDengine MCP Server

options:
  -h, --help            show this help message and exit
  -th, --taos-host TAOS_HOST
                        TDengine host address. Default: `localhost`
  -tp, --taos-port TAOS_PORT
                        TDengine port number. Default: `6041`
  -tu, --taos-username TAOS_USERNAME
                        TDengine username. Default: `root`
  -pwd, --taos-password TAOS_PASSWORD
                        TDengine password. Default: `taosdata`
  -db, --taos-database TAOS_DATABASE
                        TDengine database name. Default: `default`
  -to, --taos-timeout TAOS_TIMEOUT
                        TDengine connection timeout. Default: `30`
  -ll, --log-level LOG_LEVEL
                        Log level. Default: `INFO`
  -trans, --transport {sse,stdio}
                        The transport to use. Default: `sse`

AI アシスタントとの連携

AI アシスタントは、MCP サーバーを通じて TDengine データベースを操作できます。以下に例を示します。

クエリの例：

Can you use the query tool to show me the first 10 records from the database?

I need to analyze our sales data. Can you run a SQL query to get the total sales per region for last month from the development database?

Can you list all the available databases we have?

TDengine MCP ツールの使用

TDengine Query MCP サーバーは、AI アシスタントが使用できる主なツールを 3 つ提供します。

1. query

特定のスーパーテーブルに対して読み取り専用の SQL クエリを実行します。

Use the query tool to run:

SELECT * FROM customers WHERE itemid > '2025-01-01' LIMIT 10;

2. info

スーパーテーブルに関する詳細情報を取得します。

Use the info tool to check the meta info about the specified stable.

DESCRIBE disks_info;

セキュリティに関する考慮事項

• ✅ 読み取り専用クエリ（SELECT、SHOW、DESCRIBE）のみ許可されます

トラブルシューティング

接続の問題

接続に問題がある場合：

1. MCP の設定でデータベースの認証情報を確認してください
2. TDengine サーバーが稼働しており、アクセス可能であることを確認してください
3. 接続をブロックするファイアウォールルールがないか確認してください
4. 設定で LOG_LEVEL を指定してデバッグモードを有効にしてください

よくあるエラー

エラー：クエリの実行に失敗しました

• SQL の構文を確認してください
• サポートされているクエリタイプ（SELECT、SHOW、DESCRIBE）のみを使用していることを確認してください
• クエリが確実に読み取り専用であることを確認してください

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

---

詳細やサポートについては、GitHub リポジトリでイシューを作成してください。