AnalyticDB PostgreSQL MCP Server

AnalyticDB PostgreSQL MCP サーバー

AnalyticDB PostgreSQL MCP サーバーは、AI エージェントと AnalyticDB PostgreSQL データベースをつなぐ汎用インターフェースとして機能します。AI エージェントと AnalyticDB PostgreSQL 間のシームレスな通信を可能にし、AI エージェントがデータベースのメタデータを取得したり、SQL 操作を実行したりできるようにします。

インストール

開発用にソースコードからセットアップする方法と、直接利用するために PyPI からインストールする方法があります。

オプション 1：ソースから（開発用）

サーバーを変更したり、開発に貢献したりする場合に、この方法をお勧めします。

# 1. Clone the repository
git clone https://github.com/aliyun/alibabacloud-adbpg-mcp-server.git
cd alibabacloud-adbpg-mcp-server

# 2. Create and activate a virtual environment using uv
uv venv .venv
source .venv/bin/activate  # On Linux/macOS
# .\.venv\Scripts\activate  # On Windows

# 3. Install the project in editable mode
uv pip install -e .

オプション 2：PyPI から（本番環境／利用向け）

プロジェクト内ですぐに利用する場合に、最も簡単なインストール方法です。

pip install adbpg-mcp-server

サーバーの実行

サーバーは、MCP クライアントとの連携に使うデフォルトの stdio と、API への直接アクセスやデバッグに使う http の 2 つのトランスポートモードで実行できます。

サーバーを実行する前に、必要な環境変数を設定してください。

Stdio モード（デフォルト）

MCP クライアントとの通信に使用する標準モードです。

# Run using the default transport (stdio)
uv run adbpg-mcp-server

# Or explicitly specify the transport
uv run adbpg-mcp-server --transport stdio

Streamable-HTTP モード

HTTP サーバーを公開するモードです。テスト、デバッグ、または REST API 経由で直接連携する場合に便利です。

# Run the server in HTTP mode on the default host and port (127.0.0.1:3000)
uv run adbpg-mcp-server --transport http

# Specify a custom host and port with authentication
uv run adbpg-mcp-server --transport http --host 0.0.0.0 --port 3000 --auth-token your-secret-token

セキュリティ： 0.0.0.0 またはネットワークからアクセス可能なアドレスにバインドする場合は、必ず --auth-token または MCP_AUTH_TOKEN 環境変数で認証トークンを設定してください。トークンがない場合、/mcp エンドポイントは認証なしでアクセスできる状態になります。クライアントはすべてのリクエストに Authorization: Bearer <token> ヘッダーを含める必要があります。

MCP 連携

このサーバーを親 MCP クライアントと連携するには、クライアントの設定ファイルに以下の設定を追加してください。args 配列内の引数は、選択するトランスポートプロトコルによって異なります。

Stdio トランスポートの例

"mcpServers": {
  "adbpg-mcp-server": {
    "command": "uv",
    "args": [
      "run",
      "adbpg-mcp-server",
      "--transport",
      "stdio"
    ],
    "env": {
      "ADBPG_HOST": "host",
      "ADBPG_PORT": "port",
      "ADBPG_USER": "username",
      "ADBPG_PASSWORD": "password",
      "ADBPG_DATABASE": "database",
      "GRAPHRAG_API_KEY": "graphrag llm api key",
      "GRAPHRAG_BASE_URL": "graphrag llm base url",
      "GRAPHRAG_LLM_MODEL": "graphrag llm model name",
      "GRAPHRAG_EMBEDDING_MODEL": "graphrag embedding model name",
      "GRAPHRAG_EMBEDDING_API_KEY": "graphrag embedding api key",
      "GRAPHRAG_EMBEDDING_BASE_URL": "graphrag embedding url",
      "LLMEMORY_API_KEY": "llm memory api_key",
      "LLMEMORY_BASE_URL": "llm memory base_url",
      "LLMEMORY_LLM_MODEL": "llm memory model name",
      "LLMEMORY_EMBEDDING_MODEL": "llm memory embedding model name",
      "LLMEMORY_ENABLE_GRAPH": "enable graph engine for llm memory (Default: false)"
    }
  }
}

注： stdio がデフォルトのため、args 配列から "--transport", "stdio" を省略できます。

Streamable-HTTP トランスポートの例

"mcpServers": {
  "adbpg-mcp-server": {
    "command": "uv",
    "args": [
      "run",
      "adbpg-mcp-server",
      "--transport",
      "http",
      "--port",
      "3000"
    ],
    "env": {
      "ADBPG_HOST": "host",
      "ADBPG_PORT": "port",
      "ADBPG_USER": "username",
      "ADBPG_PASSWORD": "password",
      "ADBPG_DATABASE": "database",
      "MCP_AUTH_TOKEN": "your-secret-token",
      "GRAPHRAG_API_KEY": "graphrag llm api key",
      "GRAPHRAG_BASE_URL": "graphrag llm base url",
      "GRAPHRAG_LLM_MODEL": "graphrag llm model name",
      "GRAPHRAG_EMBEDDING_MODEL": "graphrag embedding model name",
      "GRAPHRAG_EMBEDDING_API_KEY": "graphrag embedding api key",
      "GRAPHRAG_EMBEDDING_BASE_URL": "graphrag embedding url",
      "LLMEMORY_API_KEY": "llm memory api_key",
      "LLMEMORY_BASE_URL": "llm memory base_url",
      "LLMEMORY_LLM_MODEL": "llm memory model name",
      "LLMEMORY_EMBEDDING_MODEL": "llm memory embedding model name",
      "LLMEMORY_ENABLE_GRAPH": "enable graph engine for llm memory (Default: false)"
    }
  }
}

ツール

• execute_select_sql：AnalyticDB PostgreSQL サーバーで SELECT SQL クエリを実行します

• execute_dml_sql：AnalyticDB PostgreSQL サーバーで DML（INSERT、UPDATE、DELETE）SQL クエリを実行します

• execute_ddl_sql：AnalyticDB PostgreSQL サーバーで DDL（CREATE、ALTER、DROP）SQL クエリを実行します

• analyze_table：テーブルの統計情報を収集します

• explain_query：クエリの実行計画を取得します

• adbpg_graphrag_upload

  • 説明： テキストファイル（ファイル名を含む）とファイルの内容を graphrag にアップロードし、ナレッジグラフを生成します。
  • パラメーター：
    • filename (text)：アップロードするファイルの名前です。
    • context (text)：ファイルのテキスト内容です。

• adbpg_graphrag_query

  • 説明： 指定したクエリ文字列とモードを使用して graphrag にクエリします。
  • パラメーター：
    • query_str (text)：クエリの内容です。
    • query_mode (text)：クエリモードです。[bypass, naive, local, global, hybrid, mix] から選択します。null の場合、デフォルトは mix です。

• adbpg_graphrag.upload_decision_tree(context text, root_node text)

  • 説明： 指定した root_node を持つデシジョンツリーをアップロードします。root_node が存在しない場合は、新しいデシジョンツリーが作成されます。
  • パラメーター：
    • context (text)：デシジョンツリーをテキストで表したものです。
    • root_node (text)：ルートノードの内容です。

• adbpg_graphrag.append_decision_tree(context text, root_node_id text)

  • 説明： root_node_id で指定したノードに、既存のデシジョンツリーのサブツリーを追加します。
  • パラメーター：
    • context (text)：サブツリーをテキストで表したものです。
    • root_node_id (text)：サブツリーを追加するノードの ID です。

• adbpg_graphrag.delete_decision_tree(root_node_entity text)

  • 説明： root_node_entity で指定されたノードの配下にあるサブ意思決定ツリーを削除します。
  • パラメーター：
    • root_node_entity (text)：削除するサブ意思決定ツリーのルートノードの ID。

• adbpg_llm_memory_add

  • 説明： LLM の長期メモリーを追加します。
  • パラメーター：
    • messages (json)：アップロードするファイルの名前。
    • user_id (text)：ユーザー ID。
    • run_id (text)：実行 ID。
    • agent_id (text)：エージェント ID。
    • metadata (json)：メタデータの JSON（任意）。
    • memory_type (text)：メモリーの種類（任意）。
    • prompt (text)：プロンプト（任意）。 注：
      user_id、run_id、agent_id のうち、少なくとも 1 つを指定してください。

• adbpg_llm_memory_get_all

  • 説明： 特定のユーザー、実行、またはエージェントに関連付けられたすべてのメモリーレコードを取得します。
  • パラメーター：
    • user_id (text)：ユーザー ID（任意）。指定すると、このユーザーのすべてのメモリーを取得します。
    • run_id (text)：実行 ID（任意）。
    • agent_id (text)：エージェント ID（任意）。指定すると、このエージェントのすべてのメモリーを取得します。 注：
      user_id、run_id、agent_id のうち、少なくとも 1 つを指定してください。

• adbpg_llm_memory_search

  • 説明： 特定のユーザー、実行、またはエージェントについて、指定されたクエリに関連するメモリーを取得します。
  • パラメーター：
    • query (text)：検索クエリ文字列。
    • user_id (text)：ユーザー ID（任意）。指定すると、このユーザーのすべてのメモリーを取得します。
    • run_id (text)：実行 ID（任意）。
    • agent_id (text)：エージェント ID（任意）。指定すると、このエージェントのすべてのメモリーを取得します。
    • filter (json)：JSON 形式の追加フィルター条件（任意）。 注：
      user_id、run_id、agent_id のうち、少なくとも 1 つを指定してください。

• adbpg_llm_memory_delete_all:

  • 説明： 特定のユーザー、実行、またはエージェントに関連付けられたすべてのメモリーレコードを削除します。
  • パラメーター：
    • user_id (text)：ユーザー ID（任意）。指定すると、このユーザーのすべてのメモリーを取得します。
    • run_id (text)：実行 ID（任意）。
    • agent_id (text)：エージェント ID（任意）。指定すると、このエージェントのすべてのメモリーを取得します。 注：
      user_id、run_id、agent_id のうち、少なくとも 1 つを指定してください。

リソース

組み込みリソース

• adbpg:///schemas：データベース内のすべてのスキーマを取得します

リソーステンプレート

• adbpg:///{schema}/tables：指定したスキーマ内のすべてのテーブルを一覧表示します
• adbpg:///{schema}/{table}/ddl：テーブルの DDL を取得します
• adbpg:///{schema}/{table}/statistics：テーブルの統計情報を表示します

環境変数

MCP サーバーが AnalyticDB PostgreSQL インスタンスに接続するには、次の環境変数が必要です。

• ADBPG_HOST：データベースのホストアドレス
• ADBPG_PORT：データベースのポート
• ADBPG_USER：データベースのユーザー名
• ADBPG_PASSWORD：データベースのパスワード
• ADBPG_DATABASE：データベース名

HTTP トランスポートモードでは、次の任意の変数を設定すると、エンドポイント認証を有効にできます。

• MCP_AUTH_TOKEN：HTTP エンドポイント認証用のベアラートークン（--auth-token CLI 引数でも設定できます）。ループバック以外のアドレスにバインドする場合は、強く推奨されます。

graphRAG と LLM メモリーサーバーを初期化するには、MCP サーバーに次の環境変数が必要です。

• API_KEY：LLM プロバイダーまたは埋め込み API の API キー
• BASE_URL：LLM または埋め込みサービスのエンドポイントのベース URL
• LLM_MODEL：LLM のモデル名または識別子
• EMBEDDING_MODEL：埋め込みモデルの名前または識別子

依存関係

• Python 3.11 以降
• uv（環境およびパッケージ管理用）