read-age-cypherLABSCO SUMMARY
Every limit is stated, and most of them are set low on purpose.
Read pages hold at most 50 rows, cursors carry a maximum offset of 100,000, statements time out after 30 seconds by default, and queries are capped at 100,000 characters with one explicit RETURN clause per branch — RETURN * is unsupported, so list your return values. Raw database errors and query text never reach the client, which is unusual and correct. Enabling write mode does not grant privileges the database role does not already have; use a separate least-privileged role for it.
What it is
A Cypher client for Apache AGE, the graph extension for PostgreSQL. Read-only is the default: queries run inside PostgreSQL read-only transactions, parameters are bound rather than interpolated, and pages are bounded by an authenticated cursor.
What you get
read-age-cypherruns a validated, parameterised, paginated read-only Cypher querylist-age-graphslists the graphs in the databaseget-age-schemareports counts, edge directions and sampled property types — the orientation step before writing a query- Write tools are neither advertised nor accepted unless the server starts with
--allow-write:write-age-cypherfor a mutating clause,create-age-graphanddrop-age-graph - Every tool returns MCP structured content, and an asynchronous connection pool sits underneath
Requirements
Python 3.13 or later, and PostgreSQL with the Apache AGE extension installed and loaded. Install the PyPI package age_mcp_server, version 0.3.0, with uv or pip, or through the author's Homebrew tap. Connect with PG_CONNECTION_STRING and keep the password out of the command line — PGPASSWORD or a PostgreSQL password file. Microsoft Entra authentication to Azure Database for PostgreSQL is available with an opt-in flag after an Azure CLI sign-in.
Setup effort
One command plus credentials — python3 -m pip install age_mcp_server, then supply credentials
USE CASES
01
Exploring a graph you did not build
List the graphs, read the schema with edge directions and property types, then write a query that will actually match.
02
Answering a relationship question safely
Run parameterised Cypher inside a read-only transaction, so nothing can mutate even by accident.
03
Walking a large result set
Page through with the returned cursor rather than trying to pull everything in one response.
04
Making a change deliberately
Start a separate instance with writes enabled and a least-privileged role, so the read path stays incapable of mutating.
6 tools
Listed in project docs. Your client may show a different list.
list-age-graphsget-age-schemawrite-age-cyphercreate-age-graphdrop-age-graphBEFORE YOU INSTALL
What to know first
Tools you get
6 tools named in the project's documentation.
Requires
- age_mcp_server on PATH
- Python 3.13 or later
- PG_CONNECTION_STRING in your environment
- PGPASSWORD in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
python3 -m pip install age_mcp_serverMCP Clients
Any MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"age_manager": {
"command": "age_mcp_server",
"env": {
"PG_CONNECTION_STRING": "host=db.example port=5432 dbname=postgres user=age_reader sslmode=require",
"PGPASSWORD": "<YOUR_PGPASSWORD>"
}
}
}
}Claude Desktop
CLAUDE DESKTOP · TERMINAL
uv init <YOUR_PROJECT>
cd <YOUR_PROJECT>
uv add age_mcp_serverCLAUDE DESKTOP · JSON
{
"mcpServers": {
"age_manager": {
"command": "/Users/<YOUR_USER>/.local/bin/uv",
"args": [
"--directory",
"<YOUR_PATH_TO_PROJECT>",
"run",
"age_mcp_server"
],
"env": {
"PG_CONNECTION_STRING": "host=<YOUR_SERVER>.postgres.database.azure.com port=5432 dbname=postgres user=<YOUR_USER> sslmode=require",
"PGPASSWORD": "<YOUR_PGPASSWORD>"
}
}
}
}This block is for the uv install above: <YOUR_PATH_TO_PROJECT> is the absolute path of that folder, and the uv path is the output of which uv. Set PG_CONNECTION_STRING and PGPASSWORD for your own PostgreSQL. If you installed with pip or Homebrew, use the Any MCP client block instead.
