FreePeak/db-mcp-server

A powerful multi-database server implementing the Model Context Protocol (MCP) to provide AI assistants with structured access to databases.
Overview •
Core Concepts •
Features •
Supported Databases •
Deployment Options •
Configuration •
Available Tools •
Examples •
Troubleshooting •
Contributing
📄 Product Requirements — current capabilities, roadmap & decisions
Overview
The DB MCP Server provides a standardized way for AI models to interact with multiple databases simultaneously. Built on the FreePeak/cortex framework, it enables AI assistants to execute SQL queries, manage transactions, explore schemas, and analyze performance across different database systems through a unified interface.
Core Concepts
Multi-Database Support
Unlike traditional database connectors, DB MCP Server can connect to and interact with multiple databases concurrently:
Dynamic Tool Generation
For each connected database, the server automatically generates specialized tools:
Clean Architecture
The server follows Clean Architecture principles with these layers:
1. **Domain Layer**: Core business entities and interfaces
2. **Repository Layer**: Data access implementations
3. **Use Case Layer**: Application business logic
4. **Delivery Layer**: External interfaces (MCP tools)
Features
- **Simultaneous Multi-Database Support**: Connect to multiple MySQL, PostgreSQL, SQLite, and Oracle databases concurrently
- **Lazy Loading Mode**: Defer connection establishment until first use - perfect for setups with 10+ databases (enable with --lazy-loading flag)
- **Database-Specific Tool Generation**: Auto-creates specialized tools for each connected database
- **Clean Architecture**: Modular design with clear separation of concerns
- **OpenAI Agents SDK Compatibility**: Full compatibility for seamless AI assistant integration
- **Dynamic Database Tools**: Execute queries, run statements, manage transactions, explore schemas, analyze performance
- **Unified Interface**: Consistent interaction patterns across different database types
- **Connection Management**: Simple configuration for multiple database connections
- **Health Check**: Automatic validation of database connectivity on startup
- **Production Guardrails**: Per-database read_only enforcement (blocks writes through both query_* and execute_* tools), max_rows result truncation with explicit notices, and per-query timeouts
Production Guardrails
Protect agent sessions against runaway queries and accidental writes:
| Setting | Scope | Effect |
|---------|-------|--------|
| "read_only": true | per database | Blocks write statements (INSERT, UPDATE, DELETE, DDL, data-modifying CTEs, stacked writes) through **both** query and execute tools, **and** enforces rejection at the database engine itself on PostgreSQL/TimescaleDB (default_transaction_read_only=on) and MySQL (transaction_read_only=1); SQLite opens mode=ro. Classification strips comments and string literals and defaults to deny for unrecognized statements. |
| "max_rows": 1000 | per database | Truncates result sets at N rows and appends an explicit [Truncated] notice so the model knows to refine its query instead of losing context. 0 (default) means unlimited. |
| "masking_rules": [...] | per database | Masks values of result columns whose **name** matches a rule's regex before they leave the server — applies to every query shape including SELECT *. Strategies: "fixed_string" (replace with value), "null", and "partial" (keep_last trailing characters visible; shorter values fully masked). First matching rule wins; invalid patterns or unknown strategies abort config load (fail closed); masked-cell counts are reported in the result footer. Renaming a column with an alias bypasses name matching by design. See docs/design/column-masking-scoping.md. |
| "mask_pii": true | per database | Redacts PII in query results by **content shape**, not just column name: emails, phone numbers, credit-card numbers (Luhn-checked), SSNs, IPv4 addresses and 19+ digit identifiers are replaced with [EMAIL]/[PHONE]/[CREDIT_CARD]/[SSN]/[IP_ADDRESS]/[LONG_NUMBER] wherever they appear — including inside free-text columns no rule covers. Column names like email/card_number/iban are redacted whole. Operator-controlled: once set, an agent **cannot** turn it off (the per-query mask_pii parameter is additive only). Composes with masking_rules. |
| "query_timeout": 30 | per database | Cancels statements that exceed the timeout in seconds; enforced at the repository layer for every tool (queries, statements, transactions, explain, schema inspection). Unset defaults to 30s; -1 disables. Env-only deployments can set QUERY_TIMEOUT_SECONDS to fill connections without an explicit value (JSON keeps precedence). |