pgconsole MCP server
Commit Oct 30, 2026Lets AI agents query and modify PostgreSQL through a governed MCP endpoint with per-agent permissions and audit logging.
Also known as pgplex/pgconsole
- Stars
- 162
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 30, 2026
- License
- Apache-2.0
What is pgconsole MCP?
pgconsole lets AI agents query and modify PostgreSQL through a governed MCP endpoint with per-agent permissions and audit logging.
Summary generated from the project's README
About pgconsole MCP server
Managing PostgreSQL access for AI agents through a governed endpoint is what pgconsole enables for engineering teams. It provides a way to expose database connections to external clients like Claude, Cursor, or CI bots via the Model Context Protocol without sharing raw database credentials. Users can configure the system using a single TOML file and run it via npm, npx, or Docker.
Developers use this tool to implement fine-grained access control where agents inherit specific permissions like read, write, or ddl through an IAM layer. The server supports two types of agents: pure service accounts and delegated agents acting on behalf of users. It includes an integrated SQL editor for humans and an AI assistant that works with OpenAI, Anthropic, or Google providers to perform tasks like text-to-SQL and query optimization.
Security is maintained through a default-deny policy and comprehensive audit logging. Every query and login is recorded as structured JSON to stdout, allowing teams to track actions taken by both humans and automated agents. The system ensures that tools like list_objects or query only become available once an agent has an authorized connection.
What you can do with it
- 1Securely grant agent database accessProvide an AI agent with specific permissions to query a database without exposing the actual database password.
- 2Audit all AI-driven database changesTrack every SQL statement executed by an AI agent to ensure compliance and visibility.
- 3Convert natural language to SQLUse the built-in AI assistant to transform a plain English description into a functional PostgreSQL query.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepgplex/pgconsole is public and reachablegithub.com/pgplex/pgconsole ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-30github.com/pgplex/pgconsole ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub[!NOTE] pgplex: The Postgres Toolchain for Humans and Agents - pgconsole · pgschema · pgtui · pgparser
Brought to you by Bytebase, open-source database governance platform.

pgconsole is a web-based PostgreSQL editor. Single binary, single config file, no database required. Connect your team to PostgreSQL with access control and audit logging built in.
Installation
Visit https://docs.pgconsole.com/getting-started/quickstart
Prerequisites
- Node.js 20+
npm
npm install -g @pgplex/pgconsole
pgconsole --config pgconsole.toml
npx
npx @pgplex/pgconsole --config pgconsole.toml
Docker
docker run -p 9876:9876 -v /path/to/pgconsole.toml:/etc/pgconsole.toml pgplex/pgconsole
Run without --config to start in demo mode with a bundled sample database.
Features
SQL Editor
A full-featured SQL workspace for writing, running, editing, and inspecting PostgreSQL, with parser-powered intelligence in the editor.
- Autocomplete — context-aware suggestions for tables, columns, joins, and CTEs
- Formatting — pretty-print or collapse SQL to one line
- Error detection — red underlines with hover tooltips
- Code folding — collapse
SELECT,WITH, and other blocks - Function signature help — parameter hints as you type
- Result grid & inline editing — virtual-scrolling query results with staged edits, generated SQL previews, and optional AI risk assessment before execution
- Schema browser — inspect tables, views, materialized views, functions, and procedures with metadata, indexes, constraints, triggers, and grants
AI Assistant
Generate, explain, fix, and rewrite SQL with an AI assistant that understands your schema context. Supports OpenAI, Anthropic, and Google providers.
- Text-to-SQL — describe a query in natural language, get SQL back
- Explain SQL — get plain-language explanations of any query
- Fix SQL — AI-powered error correction from inline linting
- Rewrite SQL — optimize queries for performance or readability
- Risk assessment — analyze staged changes for potential risks before execution
MCP Server
Expose your Postgres connections to external AI agents (Claude, Cursor, IDEs, CI bots) over the Model Context Protocol — without handing out raw database credentials. Agents connect to a remote MCP endpoint and inherit the same IAM, permission, and audit controls as human users.
- Remote & token-authenticated — a Streamable HTTP endpoint at
/mcp; each agent authenticates withAuthorization: Bearer <token> - Two agent kinds — a pure service account (authorized by
agent:<id>IAM rules) or a delegated agent that acts on behalf of a user, optionally capped to fewer permissions or connections - Permission-shaped tools — every agent can
list_connections; catalog tools (list_objects,describe_table) appear once it has an accessible connection, and execution tools unlock per grant:explain_query(explain),query(read),write_data(write),run_ddl(ddl) - Same governance as the UI — every statement runs through per-statement SQL permission detection, default-deny IAM, and the audit log
# A standalone agent, authorized via [[iam]] just like a user
[[agents]]
id = "ci-bot"
name = "CI Pipeline"
token = "generate-a-long-random-secret" # openssl rand -hex 32
[[iam]]
connection = "staging"
permissions = ["read", "ddl"]
members = ["agent:ci-bot"]
Database Access Control
Fine-grained IAM controls who can read, write, or administer each connection. Permissions are enforced at the application layer — no database roles needed.
- Default deny — users have no access unless a rule explicitly grants it
- Connection-scoped — permissions are granted per connection, not globally
- Disjoint permissions —
read,write,ddl,admin,explain,execute,exportare independent
Audit Log
Every query and login is recorded as structured JSON to stdout. Filter and forward to your log infrastructure.
{
"type": "audit",
"ts": "2024-01-15T10:32:15.456Z",
"action": "sql.execute",
"actor": "alice@example.com",
"connection": "prod-db",
"sql": "SELECT * FROM users WHERE active = true",
"duration_ms": 45,
"row_count": 150
}
Single-File Configuration
Everything lives in pgconsole.toml — connections, users, groups, access rules, AI providers. No database required.
[[connections]]
id = "production"
name = "Production"
host = "db.example.com"
port = 5432
database = "myapp"
username = "readonly"
password = "..."
[[iam]]
connection = "production"
permissions = ["read", "explain", "export"]
members = ["*"]
[[iam]]
connection = "production"
permissions = ["*"]
members = ["group:dba"]
[[ai.providers]]
id = "claude"
vendor = "anthropic"
model = "claude-sonnet-4-20250514"
api_key = "sk-ant-..."
Getting Help
Development
[!NOTE] For external contributors: If you want to request a feature, please create a GitHub issue to discuss first instead of creating a PR directly.
git clone https://github.com/pgplex/pgconsole.git
cd pgconsole
pnpm install
pnpm dev # Start dev server (frontend + backend)
pnpm build # Production build
pnpm test # Run all tests
Sponsor
Bytebase - open source, web-based database DevSecOps platform.
pgconsole MCP questions
How does an AI agent authenticate to the pgconsole MCP server?
Agents connect to a Streamable HTTP endpoint at /mcp and authenticate with a bearer token defined for the agent in the config file.
Which tools does an agent get on the pgconsole MCP server?
Every agent can list connections; catalog and execution tools appear based on the permissions granted to that agent.
Do agents need raw database credentials to use pgconsole?
No. Agents use the MCP endpoint and inherit the same IAM, permission, and audit controls as human users instead of database credentials.
Are agent queries audited in pgconsole?
Yes, every statement runs through SQL permission detection, default-deny IAM, and the audit log.
What kinds of agents can be configured in pgconsole?
You can configure a pure service account authorized by IAM rules, or a delegated agent that acts on behalf of a user with optionally reduced permissions.