local-db-mcp

local-db-mcp is a unified read-only MCP server for local PostgreSQL, MySQL, and Redis instances.

It is designed for AI-assisted development workflows where an agent needs safe, structured access to local databases without write privileges and without returning oversized payloads that can overwhelm the client context window.

Features

One MCP server for PostgreSQL, MySQL, and Redis
Read-only by design
Query/result truncation to keep responses bounded
Target-level enable/disable support
Safe Redis reads with bounded scans instead of unbounded full dumps
Streamed SQL row collection with early stop at configured limits
Designed for local stdio MCP clients such as Codex Desktop

Implemented tools

health_check
list_targets
list_databases
list_tables
describe_table
sample_rows
run_read_query
list_redis_keys
read_redis_key
redis_key_meta

Requirements

Runtime requirements

Linux or WSL2
Access to one or more of:
- PostgreSQL
- MySQL
- Redis

This project uses sqlx with Rustls, so you do not need system PostgreSQL or MySQL client libraries just to run the binary.

Build requirements

Rust toolchain
Cargo

Recommended installation:

curl https://sh.rustup.rs -sSf | sh
source "$HOME/.cargo/env"
rustc --version
cargo --version

Project layout

local-db-mcp/
  Cargo.toml
  README.md
  config/
    local-db.example.toml
  src/
    adapters/
    guards/
    tools/

Configuration

Copy the example config and fill in your own local connection strings:

cp config/local-db.example.toml config/local-db.toml

Example:

[server]
name = "local-db-mcp"
instructions = "Unified read-only MCP server for local PostgreSQL, MySQL, and Redis targets."
default_row_limit = 50
max_row_limit = 200
default_key_limit = 50
max_key_limit = 100
max_value_chars = 4000
query_timeout_secs = 5

[targets.pg_local]
type = "postgres"
dsn = "postgresql://YOUR_USER:YOUR_PASSWORD@127.0.0.1:5432/YOUR_DATABASE"
enabled = true

[targets.mysql_local]
type = "mysql"
dsn = "mysql://YOUR_USER:YOUR_PASSWORD@127.0.0.1:3306/YOUR_DATABASE"
enabled = false

[targets.redis_local]
type = "redis"
dsn = "redis://127.0.0.1:6379/0"
enabled = false

config/local-db.toml is intentionally ignored by git so local credentials do not end up in the repository.

Development build

cargo run -- --config config/local-db.toml

Release build

cargo build --release

The release binary will be written to:

target/release/local-db-mcp

Manual startup

This MCP server is usually launched by the client on demand, but you can start it manually for debugging:

./target/release/local-db-mcp --config config/local-db.toml

If you run it directly in a terminal, it will wait for an MCP client to send initialize. That is expected behavior for a stdio MCP server.

Codex Desktop integration

Add a local_db entry to your Codex config:

[mcp_servers.local_db]
command = "/absolute/path/to/local-db-mcp/target/release/local-db-mcp"
args = ["--config", "/absolute/path/to/local-db-mcp/config/local-db.toml"]

Example on WSL:

[mcp_servers.local_db]
command = "/home/your-user/mcp_servers/local-db-mcp/target/release/local-db-mcp"
args = ["--config", "/home/your-user/mcp_servers/local-db-mcp/config/local-db.toml"]

After updating the config, restart Codex Desktop or reload MCP servers.

Deployment notes

For a local stdio MCP deployment you typically only need:

the compiled binary
your private config/local-db.toml

This binary is dynamically linked against common Linux system libraries, so deploy it to a compatible Linux environment or WSL instance.

Suggested deployment layout:

/home/your-user/mcp_servers/local-db-mcp/
  config/local-db.toml
  target/release/local-db-mcp

Privacy and repository hygiene

Do not commit config/local-db.toml
Do not hardcode real DSNs, passwords, tokens, or secrets in source files
Keep example configuration placeholders generic
Review your config before copying screenshots or logs into issues or PRs

Safety model

This server is intentionally read-only.

Current protections include:

disallowing write-oriented SQL statements
limiting row counts before collecting full result sets
limiting Redis key scans and collection reads
truncating large values before returning them to the client
allowing targets to be disabled in config

Future improvements

Environment-variable based DSN loading
HTTP transport for remote clients
Audit logging
Optional write-enabled mode with explicit safeguards
Additional type handling and richer schema metadata

MCP Servers