AGE MCP Server

An MCP server for querying Apache AGE graphs in PostgreSQL.

Version 0.3.0 makes read-only operation the secure default, adds asynchronous connection pooling, safe Cypher parameters and bounded cursor pagination, and returns MCP structured content from every tool.

Requirements

• Python 3.13 or later
• PostgreSQL with the Apache AGE extension installed and loaded
• A database role restricted to the graphs and operations the MCP client needs

Enable AGE in the target database:

CREATE EXTENSION IF NOT EXISTS age CASCADE;

Install

With uv:

uv init your_project
cd your_project
uv add age_mcp_server

With a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install age_mcp_server

With Homebrew:

brew install rioriost/tap/age_mcp_server

Configure an MCP client

Avoid placing a database password in command-line arguments. Supply a connection string through PG_CONNECTION_STRING and use one of libpq's credential mechanisms, such as PGPASSWORD or a protected PostgreSQL password file.

{
  "mcpServers": {
    "age_manager": {
      "command": "age_mcp_server",
      "env": {
        "PG_CONNECTION_STRING": "host=db.example port=5432 dbname=postgres user=age_reader sslmode=require",
        "PGPASSWORD": "replace-with-a-secret"
      }
    }
  }
}

Treat the MCP client configuration as a secret if it contains PGPASSWORD. A PostgreSQL password file or the client's secret store is preferable.

The connection string can still be supplied explicitly when necessary:

age_mcp_server --pg-con-str "host=db.example dbname=postgres user=age_reader sslmode=require"

For Microsoft Entra authentication to Azure Database for PostgreSQL, first sign in with the Azure CLI, then opt in to token acquisition:

age_mcp_server \
  --pg-con-str "host=server.postgres.database.azure.com dbname=postgres user=identity sslmode=require" \
  --azure-identity

Tools

Read-only mode is the default:

Write tools are only advertised and accepted when the server starts with --allow-write:

age_mcp_server --allow-write

Use a separate, least-privileged database role for write mode. Enabling the flag does not grant PostgreSQL privileges that the configured role does not already have.

Safety limits

• Cypher, graph names, return aliases, and graph-management arguments are safely quoted or parameterized before reaching PostgreSQL.
• Read tools run inside PostgreSQL read-only transactions.
• CALL is considered side-effecting and requires write mode.
• Read pages contain at most 50 rows. Opaque HMAC-authenticated cursors are bound to the graph, query, and parameters, with a maximum offset of 100,000.
• Cypher $parameters are accepted only when placeholder names exactly match a JSON parameter object. The object is capped at 100,000 bytes and passed to AGE through a prepared statement.
• Write queries execute fully and return an affected-row count instead of result rows.
• Statements time out after 30 seconds by default.
• Queries are limited to 100,000 characters and must contain one explicit RETURN clause per query branch.
• Raw database errors, query contents, and connection credentials are not returned to MCP clients or written to normal logs.

Change the timeout when needed:

age_m

... [View full README on GitHub](https://github.com/rioriost/age_mcp_server#readme)