DBeast MCP server
Provides AI assistants with expert DBA capabilities for PostgreSQL schema discovery, query optimization, security auditing, and performance analysis.
Also known as snss10/DBeast, dbeast
- Stars
- 9
- Tools
- 21
- Downloads, 30 days
- —
- Latest version
- 2.0.2
- Last commit
- Aug 10, 2026
- License
- MIT
What is DBeast MCP?
DBeast provides AI assistants with expert DBA capabilities for PostgreSQL schema discovery, query optimization, security auditing, and performance analysis. It exposes 21 tools, such as connect, disconnect, health_check.
Summary generated from the project's README
About DBeast MCP server
DBeast provides AI assistants with specialized database administration capabilities for PostgreSQL environments. It functions as a local stdio MCP server that connects to various database providers including local instances, AWS RDS, Supabase, and Neon. Developers can integrate it with clients like Claude, Cursor, Windsurf, or VS Code Copilot by passing database credentials through environment variables.
Unlike a simple SQL execution tool, this server offers 21 distinct tools organized into ten functional categories. It prioritizes safety by preventing the direct execution of destructive commands like DROP or DELETE, instead providing impact previews and risk assessments. The system includes specialized tools for schema discovery, query optimization, security auditing, and maintenance analysis. Users can perform complex tasks such as detecting sensitive PII, analyzing replication lag, or generating Mermaid ERD diagrams to visualize database structures.
What you can do with it
- 1Analyze query performanceAn AI assistant can investigate slow queries and suggest specific index improvements.
- 2Perform security auditsA developer can use the assistant to scan the public schema for potential security risks and exposure.
- 3Preview destructive changesBefore running a delete command, the assistant can estimate the number of affected rows and the risk of rollback.
- 4Visualize database schemasThe assistant can generate visual diagrams representing the relationships between tables.
Written from the project's README. Every use case is checked against a quote from it.
How to install DBeast MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall DBeast MCP in Claude Code
$ claude mcp add --env 'DATABASE_URL=<YOUR_DATABASE_URL>' --env 'DB_PASSWORD=<YOUR_DB_PASSWORD>' dbeast -- docker run -i --rm ghcr.io/snss10/dbeast:2.0.2Install DBeast MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"dbeast": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/snss10/dbeast:2.0.2"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>",
"DB_PASSWORD": "<YOUR_DB_PASSWORD>"
}
}
}
}Install DBeast MCP in VS Code
.vscode/mcp.json
{
"servers": {
"dbeast": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/snss10/dbeast:2.0.2"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>",
"DB_PASSWORD": "<YOUR_DB_PASSWORD>"
}
}
}
}Install DBeast MCP in VS Code CLI
$ code --add-mcp '{"name":"dbeast","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/snss10/dbeast:2.0.2"],"env":{"DATABASE_URL":"<YOUR_DATABASE_URL>","DB_PASSWORD":"<YOUR_DB_PASSWORD>"}}'Install DBeast MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"dbeast": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/snss10/dbeast:2.0.2"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>",
"DB_PASSWORD": "<YOUR_DB_PASSWORD>"
}
}
}
}Install DBeast MCP in Codex
$ codex mcp add dbeast --env 'DATABASE_URL=<YOUR_DATABASE_URL>' --env 'DB_PASSWORD=<YOUR_DB_PASSWORD>' -- docker run -i --rm ghcr.io/snss10/dbeast:2.0.2Install DBeast MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.dbeast] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/snss10/dbeast:2.0.2"] [mcp_servers.dbeast.env] DATABASE_URL = "<YOUR_DATABASE_URL>" DB_PASSWORD = "<YOUR_DB_PASSWORD>"
Install DBeast MCP in Gemini CLI
$ gemini mcp add -s user -e 'DATABASE_URL=<YOUR_DATABASE_URL>' -e 'DB_PASSWORD=<YOUR_DB_PASSWORD>' dbeast docker -- run -i --rm ghcr.io/snss10/dbeast:2.0.2Install DBeast MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"dbeast": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/snss10/dbeast:2.0.2"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>",
"DB_PASSWORD": "<YOUR_DB_PASSWORD>"
}
}
}
}DBeast MCP tools 21
Detected from the READMEconnectdisconnecthealth_checkget_schemadependency_analysisexecute_queryanalyze_queryquery_optimizeranalyze_impactdatabase_healthquery_performancesecurity_audit
| connect | — | |
| disconnect | — | |
| health_check | — | |
| get_schema | — | |
| dependency_analysis | — | |
| execute_query | — | |
| analyze_query | — | |
| query_optimizer | — | |
| analyze_impact | — | |
| database_health | — | |
| query_performance | — | |
| security_audit | — |
Show all 21 toolsShow fewer tools
sensitive_data_scanmaintenance_analysispartition_analysisdata_quality_reportduplicate_detectionconfiguration_reviewreplication_statusget_audit_logslist_audit_files
| sensitive_data_scan | — | |
| maintenance_analysis | — | |
| partition_analysis | — | |
| data_quality_report | — | |
| duplicate_detection | — | |
| configuration_review | — | |
| replication_status | — | |
| get_audit_logs | — | |
| list_audit_files | — |
Configuration
DATABASE_URLSecretPostgreSQL connection URL, for example postgresql://user:password@host:5432/database.
DB_PASSWORDSecretPostgreSQL password when DATABASE_URL is not used.
AWS_REGIONAWS region for Secrets Manager lookup.
AWS_SECRET_NAMEAWS Secrets Manager secret containing PostgreSQL credentials.
DBEAST_AUDIT_DIRDBEAST_AUDIT_ENABLEDDB_HOSTPostgreSQL host when DATABASE_URL is not used.
DB_NAMEPostgreSQL database name when DATABASE_URL is not used.
DB_PORTPostgreSQL port when DATABASE_URL is not used.
DB_SSLMODEDB_USERPostgreSQL user when DATABASE_URL is not used.
| Name | Description | |
|---|---|---|
| DATABASE_URL | PostgreSQL connection URL, for example postgresql://user:password@host:5432/database. | Secret |
| DB_PASSWORD | PostgreSQL password when DATABASE_URL is not used. | Secret |
| AWS_REGION | AWS region for Secrets Manager lookup. | |
| AWS_SECRET_NAME | AWS Secrets Manager secret containing PostgreSQL credentials. | |
| DBEAST_AUDIT_DIR | — | |
| DBEAST_AUDIT_ENABLED | — | |
| DB_HOST | PostgreSQL host when DATABASE_URL is not used. | |
| DB_NAME | PostgreSQL database name when DATABASE_URL is not used. | |
| DB_PORT | PostgreSQL port when DATABASE_URL is not used. | |
| DB_SSLMODE | — | |
| DB_USER | PostgreSQL user when DATABASE_URL is not used. |
Automated checks
Ran Nov 14, 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 reachablesnss10/dbeast is public and reachablegithub.com/snss10/dbeast ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-10github.com/snss10/dbeast ↗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 model21 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 GitHubA PostgreSQL MCP server that gives AI assistants expert DBA capabilities.
Quick Start · Demo · Tools · Safety · Configuration · Docs
DBeast connects AI assistants such as Claude, Cursor, Windsurf, and VS Code Copilot to PostgreSQL through the Model Context Protocol. Instead of exposing one broad execute_sql escape hatch, DBeast provides 21 focused tools for schema discovery, safe query execution, impact analysis, performance review, security checks, maintenance reporting, replication monitoring, and data quality inspection.
Demo
Watch Claude use DBeast MCP tools to audit a PostgreSQL database, identify security and maintenance risks, and preview cleanup impact without executing destructive SQL.
How It Works
AI assistant --MCP stdio--> DBeast server --asyncpg--> PostgreSQL
Claude/Cursor Python local Local, RDS,
Windsurf/VS Code subprocess Supabase, Neon
DBeast runs as a local stdio MCP server. Your IDE or desktop assistant starts it as a subprocess and passes database credentials through environment variables. The assistant calls DBeast tools, DBeast queries PostgreSQL, and structured results come back to the assistant. No HTTP service or extra infrastructure is required.
Quick Start
1. Install
git clone https://github.com/snss10/DBeast.git
cd DBeast
pip install -e .
For development:
pip install -e ".[dev]"
Optional: copy .env.example to .env and set your database credentials.
2. Verify
dbeast
Or run the source entry point directly:
python src/server.py
3. Configure Your MCP Client
Minimal Cursor or Windsurf config:
{
"mcpServers": {
"dbeast": {
"type": "stdio",
"command": "python",
"args": ["/absolute/path/to/DBeast/src/server.py"],
"env": {
"DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
}
}
}
}
Common config locations:
| Client | Config location |
|---|---|
| Cursor | .mcp.json in project root, or ~/.cursor/.mcp.json globally |
| VS Code | .vscode/settings.json or user settings with key mcp.servers |
| Claude Desktop on macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop on Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Windsurf | .mcp.json |
See SETUP.md for full client examples, Docker, RDS, Supabase, Neon, SSH tunnels, AWS Secrets Manager, and troubleshooting.
4. Ask Simple or Complex Questions
Once connected, your assistant can answer quick lookup questions and also run multi-step database investigations.
Simple examples:
Show me the schema for the orders table.
Which queries are slowest right now?
Run a security audit on the public schema.
Generate a Mermaid ERD for the sales schema.
More complex examples:
Before I archive old sessions, estimate how many rows would be affected, identify related tables, and tell me the rollback risk.
Investigate why the dashboard query is slow, explain the execution plan, and suggest safe indexes.
Review the public schema for maintenance issues, security risks, and data quality problems, then summarize the top priorities.
Compare table growth, dead tuples, and index health across all schemas and recommend what to vacuum or reindex first.
Tools
DBeast exposes 21 MCP tools across 10 categories.
Connection
| Tool | Description |
|---|---|
connect |
Connect to PostgreSQL, check current status, or discover local databases |
disconnect |
Close the current database connection |
health_check |
Verify connectivity, pool health, PostgreSQL version, and extensions |
Schema Discovery
| Tool | Description |
|---|---|
get_schema |
List schemas, tables, columns, indexes, relationships, and optional Mermaid ERDs |
dependency_analysis |
Map object dependencies before renaming, dropping, or changing database objects |
Data Access
| Tool | Description |
|---|---|
execute_query |
Run read-only SELECT queries with automatic row-limit injection |
Query Analysis
| Tool | Description |
|---|---|
analyze_query |
Parse and inspect query structure, warnings, and optimization hints |
query_optimizer |
Recommend indexes and rewrites for a given query |
analyze_impact |
Preview write-query impact, risk level, affected rows, and rollback context without executing |
Database Health
| Tool | Description |
|---|---|
database_health |
Review cache hit rates, connections, transaction age, table health, and overall health signals |
query_performance |
Report slow or expensive queries from PostgreSQL statistics |
Security
| Tool | Description |
|---|---|
security_audit |
Inspect roles, privileges, superuser accounts, and public schema exposure |
sensitive_data_scan |
Detect likely PII or secrets by column names and schema patterns |
Maintenance
| Tool | Description |
|---|---|
maintenance_analysis |
Review vacuum status, dead tuples, analyze timestamps, and index health |
partition_analysis |
Inspect partition health, row distribution, and missing partition risks |
Data Quality
| Tool | Description |
|---|---|
data_quality_report |
Analyze null rates, cardinality, value distributions, and outliers |
duplicate_detection |
Find duplicate rows across selected key columns |
Server Config
| Tool | Description |
|---|---|
configuration_review |
Review PostgreSQL configuration and tuning opportunities |
replication_status |
Inspect replication lag, WAL sender/receiver state, and replication slots |
Audit
| Tool | Description |
|---|---|
get_audit_logs |
Retrieve logged MCP tool calls for a given date |
list_audit_files |
List available audit log files |
Recommended Workflow
Start by discovering schemas:
get_schema()
get_schema(schema='public')
Run safe read queries:
execute_query(query='SELECT * FROM orders ORDER BY created_at DESC')
Preview risky writes:
analyze_impact(query='DELETE FROM sessions WHERE last_active < now() - interval ''30 days''')
Check health and maintenance:
database_health()
maintenance_analysis(schema='public')
query_performance()
Most analysis tools accept a schema parameter:
maintenance_analysis(schema='public') -> analyze one schema
maintenance_analysis(schema='all') -> analyze every schema
get_schema(format='mermaid') -> generate an ERD diagram
Supported Databases
| Provider | Connection method |
|---|---|
| Local PostgreSQL | DATABASE_URL or individual DB_* variables |
| Docker PostgreSQL | Explicit variables or connect(discover=true) |
| AWS RDS / Aurora | Direct URL, SSH tunnel, or AWS Secrets Manager |
| Supabase | Pooler connection string from Dashboard settings |
| Neon | Connection string from Console connection details |
| Railway / Render / Fly.io | Provider connection string |
| Any PostgreSQL host | Standard PostgreSQL URL |
Configuration
Choose one connection method.
# Full URL
DATABASE_URL=postgresql://user:pass@host:5432/db
# Or individual variables
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=secret
DB_NAME=mydb
DB_SSLMODE=prefer
# Or AWS Secrets Manager
AWS_SECRET_NAME=my-rds-secret
AWS_REGION=us-west-2
You can also connect at runtime:
connect(url='postgresql://user:pass@host:5432/db')
connect(host='localhost', user='postgres', password='secret', database='mydb')
connect(aws_secret_name='my-secret', aws_region='us-west-2')
Key settings:
| Variable | Default | Description |
|---|---|---|
DBEAST_DEFAULT_ROW_LIMIT |
100 |
Max rows returned by execute_query |
DBEAST_QUERY_TIMEOUT |
300 |
Query execution timeout in seconds |
DBEAST_COMMAND_TIMEOUT |
300 |
SQL command timeout in seconds |
DBEAST_SSL_VERIFY |
true |
Set false for SSH tunnels where certificates do not match localhost |
DBEAST_SCHEMA_CACHE_TTL |
60 |
Schema cache TTL in seconds, 0 disables caching |
DBEAST_AUDIT_ENABLED |
true |
Log MCP tool calls |
DBEAST_AUDIT_DIR |
logs/mcp_audit |
Audit log directory |
See SETUP.md for the complete configuration reference.
Safety Model
| Query type | What DBeast does |
|---|---|
SELECT |
Executes with automatic row limits |
INSERT / UPDATE / DELETE |
Never executed; returns an impact preview |
DROP / TRUNCATE |
Never executed; reports affected objects and risk |
Formatted and JSON responses use a consistent wrapper:
{
"success": true,
"data": { "...": "..." },
"meta": {
"connected": true,
"source": "tool"
}
}
Audit Logging
DBeast logs MCP tool calls for accountability and debugging.
DBEAST_AUDIT_ENABLED=true
DBEAST_AUDIT_DIR=logs/mcp_audit
Audit files are stored as daily markdown files and include timestamps, tool names, durations, masked parameters, truncated responses, and errors.
Development
pip install -e ".[dev]"
pre-commit install
pytest tests/ -v
ruff check src/ tests/
ruff format src/ tests/
Start the optional local PostgreSQL test database:
docker compose up -d postgres
Legacy Compose:
docker-compose up -d postgres
Documentation
- SETUP.md - Full client setup, connection scenarios, configuration, and troubleshooting
- CONTRIBUTING.md - Development setup, tests, style, commits, and PR process
- CODE_OF_CONDUCT.md - Community guidelines
License
MIT
DBeast MCP questions
How do I add DBeast MCP to Claude Code?
Run claude mcp add --env 'DATABASE_URL=<YOUR_DATABASE_URL>' --env 'DB_PASSWORD=<YOUR_DB_PASSWORD>' dbeast -- docker run -i --rm ghcr.io/snss10/dbeast:2.0.2 in your terminal. Add --scope user to make it available in every project.
How do I add DBeast MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does DBeast MCP provide?
It exposes 21 tools, including connect, disconnect, health_check, get_schema, dependency_analysis.
How does the server handle data security during query execution?
For read-only SELECT queries, DBeast automatically injects row limits to prevent overwhelming the client.
Does DBeast require an HTTP service to run?
No, it runs as a local stdio MCP server where your IDE or assistant starts it as a subprocess.
