AnalyticDB PostgreSQL MCP Server

What is AnalyticDB PostgreSQL MCP Server about?

The server acts as a bridge between AI agents and AnalyticDB PostgreSQL databases, allowing agents to fetch schema information, run SELECT/DML/DDL statements, obtain execution plans, and interact with integrated GraphRAG and LLM memory services.

How to use AnalyticDB PostgreSQL MCP Server?

1. Install – either clone the repository and run with uv, or install the PyPI package adbpg_mcp_server via pip install adbpg_mcp_server.
2. Configure – add an entry to the MCP client configuration file under mcpServers with the appropriate command, arguments, and required environment variables (database connection details, GraphRAG keys, LLM‑memory keys).
3. Run – start the server (uv run adbpg-mcp-server or uvx adbpg_mcp_server).
4. Consume – AI agents can now call the exposed tools (SQL execution, table analysis, graphRAG upload/query, memory add/get/search/delete) and resources (schema, tables, DDL, statistics) through the MCP protocol.

Key Features

• Execute SELECT, DML, and DDL statements on AnalyticDB PostgreSQL.
• Retrieve database metadata: schemas, tables, DDL, statistics.
• Explain query execution plans.
• GraphRAG integration: upload documents, query knowledge graphs, manage decision trees.
• LLM long‑term memory API: add, retrieve, search, and delete memories linked to users, runs, or agents.
• Simple configuration via environment variables.
• Supports both source‑code deployment (uv) and pip‑installed package (uvx).

Use Cases

• AI‑driven data assistants that need to explore database schemas and run ad‑hoc queries.
• Knowledge‑graph augmentation where documents are uploaded to GraphRAG and later queried by agents.
• Long‑term conversational memory for agents that require context persistence across sessions.
• Automated ETL/analysis pipelines that trigger DDL/DML operations based on AI reasoning.
• Interactive analytics dashboards powered by AI agents that fetch statistics and execution plans on demand.

FAQ

• Do I need a specific Python version? Yes, Python 3.10 or higher.
• Which packages are required? mcp>=1.4.0, psycopg>=3.1.0, python-dotenv>=1.0.0, pydantic>=2.0.0.
• Can I run the server without GraphRAG or LLM memory? Yes, only set the required database env vars; the optional GraphRAG/LLMEMORY vars can be omitted if those features are not needed.
• How do I secure the credentials? Use a secrets manager or environment‑variable injection; never commit raw passwords to source control.
• What command should I use in the MCP client config? The example uses uv (or uvx for the pip package). Adjust the command and args accordingly.

AnalyticDB PostgreSQL MCP Server

AnalyticDB PostgreSQL MCP Server serves as a universal interface between AI Agents and AnalyticDB PostgreSQL databases. It enables seamless communication between AI Agents and AnalyticDB PostgreSQL, helping AI Agents retrieve database metadata and execute SQL operations.

Configuration

Mode 1: Download

Download from Github

git clone https://github.com/aliyun/alibabacloud-adbpg-mcp-server.git

MCP Integration

Add the following configuration to the MCP client configuration file:

"mcpServers": {
  "adbpg-mcp-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/adbpg-mcp-server",
      "run",
      "adbpg-mcp-server"
    ],
    "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"
    }
  }
}

Mode 2: Using pip

pip install adbpg_mcp_server

MCP Integration

"mcpServers": {
  "adbpg-mcp-server": {
    "command": "uvx",
    "args": [
      "adbpg_mcp_server"
    ],
    "env": {
      "ADBPG_HOST": "host",
      "ADBPG_PORT": "port",
      "ADBPG_USER": "username",
      "ADBPG_PASSWORD": "password",
      "ADBPG_DATABASE": "database",
      "GRAPHRAG_API_KEY": "graphrag api_key",
      "GRAPHRAG_BASE_URL": "graphrag base_url",
      "GRAPHRAG_LLM_MODEL": "graphrag 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"
    }
  }
}

Components

Tools

• execute_select_sql: Execute SELECT SQL queries on the AnalyticDB PostgreSQL server

• execute_dml_sql: Execute DML (INSERT, UPDATE, DELETE) SQL queries on the AnalyticDB PostgreSQL server

• execute_ddl_sql: Execute DDL (CREATE, ALTER, DROP) SQL queries on the AnalyticDB PostgreSQL server

• analyze_table: Collect table statistics

• explain_query: Get query execution plan

• adbpg_graphrag_upload

  • Description: Upload a text file (with its name) and file content to graphrag to generate a knowledge graph.
  • Parameters:
    • filename (text): The name of the file to be uploaded.
    • context (text): The textual content of the file.

• adbpg_graphrag_query

  • Description: Query the graphrag using the specified query string and mode.
  • Parameters:
    • query_str (text): The query content.
    • query_mode (text): The query mode, choose from [bypass, naive, local, global, hybrid, mix]. If null, defaults to mix.

• adbpg_graphrag_upload_decision_tree

  • Description: Upload a decision tree with the specified root_node. If the root_node does not exist, a new decision tree will be created.
  • Parameters:
    • context (text): The textual representation of the decision tree.
    • root_node (text): The content of the root node.

• adbpg_graphrag_append_decision_tree

  • Description: Append a subtree to an existing decision tree at the node specified by root_node_id.
  • Parameters:
    • context (text): The textual representation of the subtree.
    • root_node_id (text): The ID of the node to which the subtree will be appended.

• adbpg_graphrag_delete_decision_tree

  • Description: Delete a sub-decision tree under the node specified by root_node_entity.
  • Parameters:
    • root_node_entity (text): The ID of the root node of the sub-decision tree to be deleted.

• adbpg_llm_memory_add

  • Description: Add LLM long memory with a specific user, run or agent.

  • Parameters:

    • messages (json): The messages.
    • user_id (text): User id.
    • run_id (text): Run id.
    • agent_id (text): Agent id.
    • metadata (json): The metadata json(optional).
    • memory_type (text): The memory type(optional).
    • prompt (text): The prompt(optional).

    Note:
    At least one of user_id, run_id, or agent_id should be provided.

• adbpg_llm_memory_get_all

  • Description: Retrieves all memory records associated with a specific user, run or agent.

  • Parameters:

    • user_id (text): User ID.
    • run_id (text): Run ID.
    • agent_id (text): Agent ID.

    Note:
    At least one of user_id, run_id, or agent_id should be provided.

• adbpg_llm_memory_search

  • Description: Retrieves memories relevant to the given query for a specific user, run, or agent.

  • Parameters:

    • query (text): The search query string.
    • user_id (text): User ID.
    • run_id (text): Run ID.
    • agent_id (text): Agent ID.
    • filter (json): Additional filter conditions in JSON format (optional).

    Note:
    At least one of user_id, run_id, or agent_id should be provided.

• adbpg_llm_memory_delete_all:

  • Description: Delete all memory records associated with a specific user, run or agent.

  • Parameters:

    • user_id (text): User ID.
    • run_id (text): Run ID.
    • agent_id (text): Agent ID.

    Note:
    At least one of user_id, run_id, or agent_id should be provided.

Resources

Built-in Resources

• adbpg:///schemas: Get all schemas in the database

Resource Templates

• adbpg:///{schema}/tables: List all tables in a specific schema
• adbpg:///{schema}/{table}/ddl: Get table DDL
• adbpg:///{schema}/{table}/statistics: Show table statistics

Environment Variables

MCP Server requires the following environment variables to connect to AnalyticDB PostgreSQL instance:

• ADBPG_HOST: Database host address
• ADBPG_PORT: Database port
• ADBPG_USER: Database username
• ADBPG_PASSWORD: Database password
• ADBPG_DATABASE: Database name

MCP Server requires the following environment variables to initialize graphRAG and llm memory server：

• GRAPHRAG_API_KEY: API key for LLM provider

• GRAPHRAG_BASE_URL: Base URL for LLM service endpoint

• GRAPHRAG_LLM_MODEL: LLM model name or identifier

• GRAPHRAG_EMBEDDING_MODEL: Embedding model name or identifier

• GRAPHRAG_EMBEDDING_API_KEY: API key for embedding model provider

• GRAPHRAG_EMBEDDING_BASE_URL: Base URL for embedding service endpoint

• GRAPHRAG_LANGUAGE: (Optional)The language used by graphrag. Defaults to English if not set.

• GRAPHRAG_ENTITY_TYPES: (Optional) Specifies the types of entity nodes to be extracted when parsing the document to generate the knowledge graph.

• GRAPHRAG_RELATIONSHIP_TYPES: (Optional) Specifies the types of relationship edges to be extracted when parsing the document to generate the knowledge graph.

• LLMEMORY_API_KEY: API key for LLM provider or embedding API

• LLMEMORY_BASE_URL: Base URL for LLM or embedding service endpoint

• LLMEMORY_LLM_MODEL: LLM model name or identifier

• LLMEMORY_EMBEDDING_MODEL: Embedding model name or identifier

Dependencies

• Python 3.10 or higher
• Required packages:
  • mcp >= 1.4.0
  • psycopg >= 3.1.0
  • python-dotenv >= 1.0.0
  • pydantic >= 2.0.0

Running

# Create and activate virtual environment
uv venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# Install dependencies
uv pip install -e .

# Run server
uv run adbpg-mcp-server