query_databaseLABSCO SUMMARY
Read-only from the BEGIN, not from a promise.
Most database servers say read-only and mean they hope the model behaves. Here the read-only property is requested as part of opening the transaction, and statements are additionally screened for the constructs that would escape it — the documentation is explicit that an earlier design set it after the transaction had already begun, and that this replaces it. Being able to disable individual tools so they never appear in the tool list is the other useful control: an agent cannot call what it was never offered.
What it is
A Go MCP server for PostgreSQL that adds semantic search on top of ordinary querying. The read-only guarantee is the design centre: the server asks for read-only access as part of the BEGIN that opens each transaction, so there is no window in which the transaction is writable.
What you get
- query_database — SQL in a read-only transaction unless the connection explicitly sets allow_writes; statements are also screened for constructs known to escape read-only mode
- get_schema_info — tables, columns and relationships, so the model writes queries against the real shape
- count_rows, which always runs read-only so the screening applies even on a connection that permits writes
- execute_explain — read the plan rather than guessing why a query is slow
- Several databases at once — list_database_connections and select_database_connection
- Semantic search over your own data — generate_embedding and similarity_search
- search_knowledgebase for retrieval over an indexed corpus, and read_resource, which is always enabled because listing resources depends on it
- Any individual tool can be disabled in the server configuration — a disabled tool is not advertised in tools/list at all, and calling it returns an error
- Four prompts that carry a whole workflow: setup, explore, diagnose and design
Requirements
A reachable PostgreSQL database and a connection string. The server is a Go binary, configured through a file or environment variables, and several database connections can be registered so one server serves more than one database. Writes are off unless a connection sets allow_writes — attempting one otherwise fails with Postgres's own read-only transaction error rather than being silently dropped. Semantic search needs an embedding provider configured.
Setup effort
Build from source — git clone https://github.com/pgEdge/pgedge-postgres-mcp.git
USE CASES
01
Asking questions of a database you did not design
Read the schema and relationships first, then let the assistant write the query.
02
Giving an analyst database access without giving them write access
Leave writes off, so every query opens read-only and unsafe constructs are refused.
03
A query that is slower than it should be
Read the plan and check the row counts it is working from.
04
Searching text by meaning rather than by LIKE
Generate the embeddings and run similarity search over your own rows.
05
Working across development and production
Register both connections and switch between them in the session.
06
Getting started on an unfamiliar schema
Use the explore prompt, which carries the whole workflow rather than one call.
10 tools
Listed in project docs. Your client may show a different list.
get_schema_infosimilarity_searchexecute_explaingenerate_embeddingsearch_knowledgebasecount_rowsread_resourcelist_database_connectionsselect_database_connectionBEFORE YOU INSTALL
What to know first
Tools you get
10 tools named in the project's documentation. Tools can be disabled in server configuration, though read_resource is always on. Queries run in read-only transactions by default.
Requires
- Go 1.21 or later
- PostgreSQL 14 or later
- PGEDGE_DB_USER in your environment
- PGEDGE_DB_PASSWORD in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone https://github.com/pgEdge/pgedge-postgres-mcp.git
cd pgedge-postgres-mcp
make buildMCP Clients
Claude Code — package
Debian / Ubuntu — add the pgEdge package repository and install the server:
CLAUDE CODE — PACKAGE · TERMINAL
sudo apt-get update
sudo apt-get install -y curl gnupg2 lsb-release
sudo curl -sSL https://apt.pgedge.com/repodeb/pgedge-release_latest_all.deb -o /tmp/pgedge-release.deb
sudo dpkg -i /tmp/pgedge-release.deb
rm -f /tmp/pgedge-release.deb
sudo apt-get update
sudo apt-get install -y pgedge-postgres-mcpOn RHEL / Rocky / Alma Linux use instead: sudo dnf install -y https://dnf.pgedge.com/reporpm/pgedge-release-latest.noarch.rpm, then sudo dnf install -y pgedge-postgres-mcp
Edit /etc/pgedge/postgres-mcp.yaml: under databases, set name, host, port, database, user and password for your PostgreSQL database — at least one connection is required.
Create .mcp.json in your project directory with:
CLAUDE CODE — PACKAGE · JSON
{
"mcpServers": {
"pgedge": {
"command": "/usr/bin/pgedge-postgres-mcp",
"args": [
"-config",
"/etc/pgedge/postgres-mcp.yaml"
]
}
}
}Claude Code — binary
CLAUDE CODE — BINARY · JSON
{
"mcpServers": {
"pgedge": {
"command": "<YOUR_PATH_TO_PGEDGE_POSTGRES_MCP>",
"args": [
"-config",
"<YOUR_PATH_TO_POSTGRES_MCP>"
]
}
}
}Claude Code — Docker
CLAUDE CODE — DOCKER · JSON
{
"mcpServers": {
"pgedge": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host",
"host.docker.internal:host-gateway",
"-e",
"PGEDGE_DB_HOST=host.docker.internal",
"-e",
"PGEDGE_DB_PORT=5432",
"-e",
"PGEDGE_DB_NAME=mydb",
"-e",
"PGEDGE_DB_USER=myuser",
"-e",
"PGEDGE_DB_PASSWORD=mypass",
"ghcr.io/pgedge/postgres-mcp:latest"
]
}
}
}Claude Code — local build
CLAUDE CODE — LOCAL BUILD · JSON
{
"mcpServers": {
"pgedge": {
"command": "<YOUR_PATH_TO_PGEDGE_POSTGRES_MCP>/bin/pgedge-postgres-mcp",
"args": [
"-config",
"<YOUR_PATH_TO_PGEDGE_POSTGRES_MCP>/bin/postgres-mcp.yaml"
]
}
}
}pgEdge CLI
Add the pgEdge package repository as in the Claude Code — package tab, then install the CLI client:
PGEDGE CLI · TERMINAL
sudo apt-get install -y pgedge-nla-cliSet your LLM API key and start the CLI against the installed server:
PGEDGE CLI · TERMINAL
export PGEDGE_ANTHROPIC_API_KEY=<YOUR_PGEDGE_ANTHROPIC_API_KEY>
pgedge-nla-cli -mcp-mode stdio -mcp-server-path /usr/bin/pgedge-postgres-mcp -mcp-server-config /etc/pgedge/postgres-mcp.yaml
