@vdeserto/mcp-database-explorer

Universal read-only MCP server for SQL databases. Connect Claude, Gemini, and Codex to your database with a single interactive setup wizard — no manual JSON editing required.

Supported Databases

| Database | Driver | |-------------|----------------| | PostgreSQL | pg | | MySQL | mysql2 | | SQL Server | mssql | | Oracle | oracledb | | SQLite | better-sqlite3 |

Supported AI Clients

• Claude Desktop
• Claude Code
• Gemini CLI
• Codex CLI

Quick Start

npx @vdeserto/mcp-database-explorer

The interactive wizard will ask you to choose your database, AI client, and OS — then write the configuration file automatically.

After the wizard finishes, restart your AI client and the tools will be available.

Available Tools

| Tool | Description | |------|-------------| | db_list_schemas | Lists all schemas/databases visible to the connected user | | db_list_tables | Lists tables in a schema with optional filter and pagination | | db_describe_table | Returns column definitions, types, primary key, and indexes | | db_execute_query | Executes a read-only SELECT statement with bind parameters | | db_get_table_data | Retrieves rows with structured filters, ordering, and pagination | | db_usage_report | Shows token usage, query count, and timing for the current session | | db_usage_history | Shows usage across previous sessions (requires persistent storage) | | db_reset_usage | Clears usage counters for the current session |

Security

• Read-only enforcement — SET TRANSACTION READ ONLY at the DB session level for PostgreSQL, MySQL, Oracle, and SQLite ({ readonly: true }). SQL Server uses query-level validation.
• SQL validation — Blocks INSERT, UPDATE, DELETE, DROP, EXEC, and database-specific attack vectors (Oracle DBMS_*/UTL_*, SQL Server xp_*/OPENROWSET, MySQL LOAD_FILE/INTO OUTFILE).
• Rate limiting — 30 queries/minute, 500 queries/hour per session (sliding window).
• Error sanitization — Database error messages are mapped to safe generic messages to avoid leaking schema details or stack traces.
• Unicode normalization — NFKC normalization prevents homoglyph injection attacks.
• Identifier validation — Schema, table, and column names are validated before use.

Observability

• Token estimation — Estimates input/output tokens per query, adjusted for model reasoning type (Claude Thinking, Gemini Thinking, o1) and SQL complexity.
• Query complexity analysis — 19 pattern signals (subqueries, joins, window functions, CTEs, etc.) classify each query as simple / moderate / complex / very complex.
• Persistent usage store — Metrics saved to ~/.mcp-database-explorer/usage.db (SQLite) and available across sessions via db_usage_history.
• Session tracking — Each server startup generates a unique session ID for usage isolation.

Manual Configuration

If you prefer to configure manually, pass environment variables to the MCP server:

| Variable | Required | Description | |----------|----------|-------------| | DB_MCP_DRIVER | Yes | postgres, mysql, sqlserver, oracle, sqlite | | DB_MCP_HOST | Conditional | Database host | | DB_MCP_PORT | No | Database port | | DB_MCP_DATABASE | Conditional | Database/schema name | | DB_MCP_USER | Conditional | Username | | DB_MCP_PASSWORD | No | Password | | DB_MCP_CONNECTION_STRING | Conditional | Full connection string (overrides host/port/database) | | DB_MCP_MODEL | No | claude, claude-thinking, gemini, gemini-thinking, codex, o1 |

Claude Desktop (example)

{
  "mcpServers": {
    "mcp-database-explorer": {
      "command": "npx",
      "args": ["-y", "@vdeserto/mcp-database-explorer", "serve"],
      "env": {
        "DB_MCP_DRIVER": "postgres",
        "DB_MCP_HOST": "localhost",
        "DB_MCP_PORT": "5432",
        "DB_MCP_DATABASE": "mydb",
        "DB_MCP_USER": "myuser",
        "DB_MCP_PASSWORD": "mypassword",
        "DB_MCP_MODEL": "claude"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "mcp-database-explorer": {
      "command": "npx",
      "args": ["-y", "@vdeserto/mcp-database-explorer", "serve"],
      "env": {
        "DB_MCP_DRIVER": "postgres",
        "DB_MCP_HOST": "localhost",
        "DB_MCP_PORT": "5432",
        "DB_MCP_DATABASE": "mydb",
        "DB_MCP_USER": "myuser",
        "DB_MCP_PASSWORD": "mypassword",
        "DB_MCP_MODEL": "gemini"
      }
    }
  }
}

License

MIT