ADB-PG IMV MCP Server

Connect your AnalyticDB for PostgreSQL (ADB-PG) instance to Cursor, Claude, Qoder, and other AI assistants to manage Incremental Materialized Views (IMV).

The Model Context Protocol (MCP) standardizes how Large Language Models (LLMs) talk to external services. This server connects AI assistants directly to an ADB-PG instance through the Aliyun DataAPI, exposing IMV creation, monitoring, diagnostics, and index / distribution-key optimization as a set of structured tools. See the full list of tools.

Prerequisites

You will need Node.js version 26.0.0 or later installed on your machine (this is the version we actually test against). You can check this by running:

node -v

If you don't have Node.js installed, you can download it from nodejs.org.

You will also need:

• An ADB-PG instance with the IMV feature available (incremental materialized views are provided as an instance capability tied to the minor version).
• A database account (username / password) for connecting to the target database. A least-privilege account is recommended — avoid superusers.

Setup

1. Aliyun AccessKey

First, go to your Aliyun RAM console and create an AccessKey pair. We recommend a least-privilege RAM sub-account rather than the primary account. The key needs permission to call the instance's DataAPI — ExecuteStatement, CreateSecret, DeleteSecret, and ListSecrets (the last two let the server automatically recreate the secret after a database password rotation). If you omit IMV_REGION_ID, it also needs DescribeDBInstanceAttribute to auto-discover the instance's region.

Make sure to copy the AccessKey Secret, as you won't be able to see it again.

2. Configure MCP client

Next, configure your MCP client to use this server. Most MCP clients store the configuration as JSON in the following format:

{
  "mcpServers": {
    "imv-mcp": {
      "command": "npx",
      "args": ["-y", "@adbpg-imv/imv-mcp-server@latest"],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "<your-ak-id>",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<your-ak-secret>",
        "IMV_DB_INSTANCE_ID": "<your-instance-id>",
        "IMV_DATABASE": "<your-database>",
        "IMV_DB_USERNAME": "<your-db-user>",
        "IMV_DB_PASSWORD": "<your-db-password>"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | ALIBABA_CLOUD_ACCESS_KEY_ID | Yes | Aliyun AccessKey ID | | ALIBABA_CLOUD_ACCESS_KEY_SECRET | Yes | Aliyun AccessKey Secret | | ALIBABA_CLOUD_SECURITY_TOKEN | No | STS token, only needed when using temporary credentials | | IMV_REGION_ID | No | Instance region. If omitted, it is auto-discovered from the instance ID at startup (requires the DescribeDBInstanceAttribute permission). If set, it must match the instance's actual region, otherwise calls fail with Instance.NotFound | | IMV_DB_INSTANCE_ID | Yes | ADB-PG instance ID (e.g. gp-xxxxxxxx) | | IMV_DATABASE | No | Default target database. If omitted, every tool call must specify the database parameter instead — useful when different editor windows / agents need to work on different databases of the same instance | | IMV_DB_USERNAME | Yes | Database user | | IMV_DB_PASSWORD | Yes | Database password |

Tools

Note: This server is pre-1.0, so expect some breaking changes between versions. Since LLMs automatically adapt to the tools available, this shouldn't affect most users.

The following tools are available to the LLM. The Monitoring & diagnostics and Inspection groups are read-only; the IMV lifecycle and Schema operations groups perform writes and require the agent to confirm before running.

Monitoring & diagnostics

• imv_latency: Reports the incremental-maintenance lag (in seconds) for each base table pipeline.
• imv_error_log: Returns the most recent incremental-maintenance error records.
• imv_incremental_stat: Incremental-maintenance timing statistics (avg / max), filterable by base table or MV.
• imv_is_ready: Reports whether an IMV has finished initialization and is ready to query.
• adbpg_diagnose_skew_single: Detects data skew for a single object.

Inspection

• imv_list_all: Lists all IMV names in the database (newest first).
• imv_stat_single: Full snapshot of a single IMV (size / rows / reloptions / timestamps / access heat).
• imv_dependency: Upstream / downstream dependency graph, parameterized by direction and depth (including nested IMVs).
• imv_get_viewdef: Returns an IMV's definition (either the view creation definition or the maintain definition).
• adbpg_list_columns: Lists the columns of a relation.
• adbpg_list_indexes: Lists all indexes on a relation.
• adbpg_index_definition: Returns the CREATE INDEX definition of a specific index.
• adbpg_uniqueness_ratio: Column-combination uniqueness ratio (NDV / row count).
• imv_optimize: Checks an IMV's index and distribution key, returning diagnostic facts and optimization advice.

IMV lifecycle (write)

• imv_init_ddl: Initializes the DDL environment by creating the public.imv_ddl helper function according to the instance's capabilities.
• imv_create: Creates an IMV (via the imv_ddl function; runs asynchronously).
• imv_replace: Replaces an IMV definition (CREATE OR REPLACE; runs asynchronously).
• imv_refresh_self: Performs a READABLE full refresh of a single IMV.
• imv_drop: Drops a materialized view (CASCADE is disabled at the tool layer).
• imv_alter_maintain_index: Atomically replaces an IMV's incremental-maintenance index with the specified columns (single-transaction swap into the canonical imv<oid>_index name; the oid is resolved inside the SQL). This index serves incremental apply performance only — never change it for query-performance purposes.

Schema operations (write)

• adbpg_create_index: Creates a btree index on the specified columns.
• adbpg_drop_index: Drops an index.
• adbpg_create_view: Creates a plain view (CREATE VIEW ... AS SELECT; or_replace switches to CREATE OR REPLACE VIEW).
• adbpg_drop_view: Drops a view (CASCADE is disabled at the tool layer).
• adbpg_relation_alter_access_method: Changes the storage engine (heap / ao_row / ao_column).
• adbpg_relation_alter_distributed: Changes the distribution key or switches to REPLICATED.
• adbpg_relation_alter_rename: Renames a TABLE / VIEW / MATERIALIZED VIEW / INDEX.

Security risks

Connecting any data source to an LLM carries inherent risks, especially when it stores sensitive data.

Prompt injection

Like all MCP servers that can run database operations, this server returns database content (error messages, view definitions, query results) to the LLM. If that content contains maliciously crafted instruction text, an LLM might be tricked into treating it as a command. Most MCP clients ask you to manually approve each tool call — we recommend keeping that setting enabled and reviewing tool calls before they run. To lower the risk further, prefer connecting to non-production or controlled data sources, and grant the database account least privilege.

Built-in safeguards

Tool inputs are validated at runtime before SQL is composed. The server enforces each tool's required fields, primitive types, and declared enums; it does not rely on MCP-client schema validation alone:

• Identifiers (schema / table / column / index names) may only match [a-zA-Z_][a-zA-Z0-9_.]*, otherwise the call throws — closing off object-name injection.
• View-definition fragments (the select_sql of imv_create / imv_replace / adbpg_create_view) must start with SELECT / WITH and may not contain semicolons, comments, or DDL/DML keywords.
• Parameter values are escaped into PostgreSQL literals so injection strings cannot escape the string context.
• Destructive operations: imv_drop disables CASCADE; the agent is expected to confirm object names with the user before running delete-style tools.
• Credentials are never leaked: all outgoing error text and diagnostic logs are passed through a redaction step that strips Password / AccessKeyId / Signature / SecurityToken and any known plaintext password before output. Passwords and AccessKeys are never persisted in plaintext.
• Local secret cache: on first use the server creates a DataAPI secret and caches its ARN in .imv-secret-cache.json (file mode 0600) inside the server's install directory. The file stores the ARN, a SHA-256 config fingerprint, instance ID, database username, and region — never the plaintext password or AccessKey. You can delete it at any time; the secret is recreated automatically on the next call.

License

This project is licensed under Apache 2.0. See the LICENSE file for details.