Provides AI clients with safe, structured access to PostgreSQL databases using controlled SQL execution and schema searching.
Also known as arifulislamat/database-mcp, @database-mcp/postgres
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- 738
- Latest version
- 0.5.0
- Last commit
- Nov 1, 2026
- License
- MIT
What is database-mcp-postgres MCP?
database-mcp-postgres provides AI clients with safe, structured access to PostgreSQL databases using controlled SQL execution and schema searching.
Summary generated from the project's README
About database-mcp-postgres MCP server
Connecting AI clients to PostgreSQL databases with safety and structure is the primary function of this server. It provides a minimal interface consisting of two specific tools, execute_sql and search_objects, to ensure the model's context window remains clean. Developers can use this to allow an AI to explore schemas and run queries without overwhelming the system with unnecessary data.
Security is built into the core design through default guardrails like read-only mode, statement timeouts, and row caps. For instance, results are limited to 1000 rows by default and queries time out after 30 seconds. Connection details and credentials are managed through environment variables, YAML configuration files, or command line flags rather than through chat prompts, ensuring sensitive information stays out of the conversation and logs.
This server is available in multiple implementations including TypeScript via npm, Python through PyPI, and Rust via crates.io. Users can configure the connection using a DSN or specific environment variables like POSTGRES_URL to establish a secure link to their database.
What you can do with it
- 1Exploring database schemasAn AI can progressively discover tables, columns, and foreign keys by using the search tool.
- 2Executing controlled SQL queriesDevelopers can allow an AI to run specific SQL commands while maintaining safety through built-in limits.
- 3Preventing resource exhaustionThe server automatically manages query performance by capping the number of returned rows and setting time limits.
Written from the project's README. Every use case is checked against a quote from it.
How to install database-mcp-postgres MCP
Formats verified 10 Nov 2026Install database-mcp-postgres MCP in Claude Code
$ claude mcp add --env POSTGRES_DATABASE=<POSTGRES_DATABASE> --env POSTGRES_HOST=<POSTGRES_HOST> --env POSTGRES_USER=<POSTGRES_USER> --env POSTGRES_PASSWORD=<YOUR_POSTGRES_PASSWORD> database-mcp-postgres -- npx -y @database-mcp/postgresInstall database-mcp-postgres MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"database-mcp-postgres": {
"command": "npx",
"args": [
"-y",
"@database-mcp/postgres"
],
"env": {
"POSTGRES_DATABASE": "<POSTGRES_DATABASE>",
"POSTGRES_HOST": "<POSTGRES_HOST>",
"POSTGRES_USER": "<POSTGRES_USER>",
"POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
}
}
}
}Install database-mcp-postgres MCP in VS Code
.vscode/mcp.json
{
"servers": {
"database-mcp-postgres": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@database-mcp/postgres"
],
"env": {
"POSTGRES_DATABASE": "<POSTGRES_DATABASE>",
"POSTGRES_HOST": "<POSTGRES_HOST>",
"POSTGRES_USER": "<POSTGRES_USER>",
"POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
}
}
}
}Install database-mcp-postgres MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"database-mcp-postgres": {
"command": "npx",
"args": [
"-y",
"@database-mcp/postgres"
],
"env": {
"POSTGRES_DATABASE": "<POSTGRES_DATABASE>",
"POSTGRES_HOST": "<POSTGRES_HOST>",
"POSTGRES_USER": "<POSTGRES_USER>",
"POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
}
}
}
}Install database-mcp-postgres MCP in Codex
~/.codex/config.toml
[mcp_servers.database-mcp-postgres] command = "npx" args = ["-y", "@database-mcp/postgres"] [mcp_servers.database-mcp-postgres.env] POSTGRES_DATABASE = "<POSTGRES_DATABASE>" POSTGRES_HOST = "<POSTGRES_HOST>" POSTGRES_USER = "<POSTGRES_USER>" POSTGRES_PASSWORD = "<YOUR_POSTGRES_PASSWORD>"
Install database-mcp-postgres MCP in Gemini CLI
~/.gemini/settings.json
{
"mcpServers": {
"database-mcp-postgres": {
"command": "npx",
"args": [
"-y",
"@database-mcp/postgres"
],
"env": {
"POSTGRES_DATABASE": "<POSTGRES_DATABASE>",
"POSTGRES_HOST": "<POSTGRES_HOST>",
"POSTGRES_USER": "<POSTGRES_USER>",
"POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
}
}
}
}Configuration
POSTGRES_DATABASERequiredDatabase name
POSTGRES_DATABASERequiredDatabase name
POSTGRES_DATABASERequiredDatabase name
POSTGRES_HOSTRequiredDatabase host
POSTGRES_HOSTRequiredDatabase host
POSTGRES_HOSTRequiredDatabase host
POSTGRES_USERRequiredDatabase user (a read-only user is recommended)
POSTGRES_USERRequiredDatabase user (a read-only user is recommended)
POSTGRES_USERRequiredDatabase user (a read-only user is recommended)
POSTGRES_PASSWORDSecretDatabase password (or use POSTGRES_PASSWORD_FILE)
POSTGRES_PASSWORDSecretDatabase password (or use POSTGRES_PASSWORD_FILE)
POSTGRES_PASSWORDSecretDatabase password (or use POSTGRES_PASSWORD_FILE)
| Name | Description | |
|---|---|---|
| POSTGRES_DATABASE | Database name | Required |
| POSTGRES_DATABASE | Database name | Required |
| POSTGRES_DATABASE | Database name | Required |
| POSTGRES_HOST | Database host | Required |
| POSTGRES_HOST | Database host | Required |
| POSTGRES_HOST | Database host | Required |
| POSTGRES_USER | Database user (a read-only user is recommended) | Required |
| POSTGRES_USER | Database user (a read-only user is recommended) | Required |
| POSTGRES_USER | Database user (a read-only user is recommended) | Required |
| POSTGRES_PASSWORD | Database password (or use POSTGRES_PASSWORD_FILE) | Secret |
| POSTGRES_PASSWORD | Database password (or use POSTGRES_PASSWORD_FILE) | Secret |
| POSTGRES_PASSWORD | Database password (or use POSTGRES_PASSWORD_FILE) | Secret |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubdatabase-mcp
MCP servers that give AI clients safe, structured access to SQL databases.
One installable package per database engine, in TypeScript (npm), Python
(PyPI), and Rust (crates.io). Every package exposes the same minimal
two-tool surface, execute_sql and search_objects, with guardrails on by
default: read-only mode, row caps, and statement timeouts.
Packages
| Engine | TypeScript (npm) | Python (PyPI) | Rust (crates.io) |
|---|---|---|---|
| SQLite | @database-mcp/sqlite  |
database-mcp-sqlite  |
database-mcp-rs-sqlite  |
| libSQL | @database-mcp/libsql  |
database-mcp-libsql  |
database-mcp-rs-libsql  |
| MySQL | @database-mcp/mysql  |
database-mcp-mysql  |
database-mcp-rs-mysql  |
| MariaDB | @database-mcp/mariadb  |
database-mcp-mariadb  |
database-mcp-rs-mariadb  |
| Postgres | @database-mcp/postgres  |
database-mcp-postgres  |
database-mcp-rs-postgres  |
All three lines are published and pass the same language-agnostic conformance suite against real databases in CI, so behavior is identical regardless of language. Every engine is also listed on the MCP Registry with all three install options: npm, PyPI, and cargo.
Rust crates are named database-mcp-rs-<engine> because the plain names are
taken on crates.io; the command each one installs is still
database-mcp-<engine>. Go is planned.
Design principles
- Two tools, no more. A tiny tool surface keeps the model's context window
clean.
search_objectsprogressively discloses schema: call it with no arguments to list tables, with a table name to get columns, indexes, and foreign keys. - Safe by default. Read-only mode is enforced in two layers: a conservative SQL guard, plus a session-level read-only setting in the database itself. Rows are capped (default 1000) and statements time out (default 30s).
- Configured at launch, never via chat. Connection details come from flags, a YAML config file, or environment variables. Credentials are never accepted through a tool call.
- Secrets never appear in logs. Passwords live in non-printable secret types, DSNs are sanitized before logging, and a redaction filter guards the log boundary.
Quick start
Pick your engine's package; each README has the full config surface. SQLite via npm:
{
"mcpServers": {
"sqlite": {
"command": "npx",
"args": ["-y", "@database-mcp/sqlite", "--dsn", "/absolute/path/to/database.db"]
}
}
}
Or via PyPI: use "command": "uvx" and
"args": ["database-mcp-sqlite", "--dsn", "/absolute/path/to/database.db"].
Or as a native binary, with no Node or Python runtime: run
cargo install database-mcp-rs-sqlite, then use
"command": "database-mcp-sqlite" with the same args minus the package
name.
Flags, environment variables, and YAML config are identical across all three lines.
Networked engines take credentials from the environment (MYSQL_*,
MARIADB_*, POSTGRES_*/DATABASE_URL, LIBSQL_URL/LIBSQL_AUTH_TOKEN),
*_FILE mounted secrets, or a YAML file via --config. Never from a chat
prompt.
Contributing
See CONTRIBUTING.md. The short version: the conformance
suite is the definition of done. A change is mergeable only when
conformance/run.mjs passes against every affected server.
License
database-mcp-postgres MCP questions
How do I add database-mcp-postgres MCP to Claude Code?
Run claude mcp add --env POSTGRES_DATABASE=<POSTGRES_DATABASE> --env POSTGRES_HOST=<POSTGRES_HOST> --env POSTGRES_USER=<POSTGRES_USER> --env POSTGRES_PASSWORD=<YOUR_POSTGRES_PASSWORD> database-mcp-postgres -- npx -y @database-mcp/postgres in your terminal. Add --scope user to make it available in every project.
How do I add database-mcp-postgres MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does the server ensure database safety?
It uses a two-layer read-only enforcement consisting of a conservative SQL guard and a session-level read-only setting in the database.
What are the default limits for queries?
The server defaults to a 1000 row cap and a 30-second statement timeout.
How are database credentials handled?
Credentials are provided via flags, environment variables, or YAML configuration files and are never accepted through chat prompts.
Are database passwords visible in logs?
No, passwords use non-printable secret types and DSNs are sanitized to ensure secrets never appear in logs.