Skip to main content
Glama
Sign In
mcp-database

mcp-database

by jovian-zhibai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

mcp-database

PyPI CI Python License MCP

MCP server for multi-database access — query, inspect schema, and manage SQLite, PostgreSQL, and MySQL databases through Claude.

Why mcp-database?

Problem

Solution

Need to query a database from Claude Code / Claude Desktop

One MCP server, multiple database support

Existing database MCP servers are JS/Go only

Pure Python, uses official mcp SDK

Worried about accidental writes

Read-only by default, writes opt-in

Don't know the schema

Built-in schema inspection, table info, search

Related MCP server: Raja SQL MCP

Why mcp-database? (vs alternatives)

Feature

mcp-database

@modelcontextprotocol/sqlite

Other MCP DB Servers

Multi-database (SQLite + PG + MySQL)

✅

❌ SQLite only

Varies

Multi-connection

✅

❌

❌

Schema diff

✅

❌

❌

ER diagram (Mermaid)

✅

❌

❌

Health check

✅

❌

❌

Explain query

✅

❌

❌

Data masking

✅

❌

❌

Query timeout

✅

❌

❌

Read-only default

✅

✅

Varies

Pure Python

✅

❌ (TypeScript)

Varies

Quick Start

# Install
pip install mcp-database

# Run with a SQLite database
MCP_DATABASE_URL=sqlite:///path/to/your.db mcp-database

Claude Code Integration

# Add to Claude Code
claude mcp add mcp-database -- mcp-database

# Or with a specific database
claude mcp add mcp-database -e MCP_DATABASE_URL=sqlite:///path/to/db.sqlite -- mcp-database

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "database": {
      "command": "mcp-database",
      "env": {
        "MCP_DATABASE_URL": "sqlite:///path/to/your.db"
      }
    }
  }
}

Cursor Integration

Add to your Cursor MCP settings (Settings → MCP):

{
  "mcpServers": {
    "database": {
      "command": "mcp-database",
      "env": {
        "MCP_DATABASE_URL": "sqlite:///path/to/your.db"
      }
    }
  }
}

Windsurf Integration

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "database": {
      "command": "mcp-database",
      "env": {
        "MCP_DATABASE_URL": "sqlite:///path/to/your.db"
      }
    }
  }
}

Other MCP-Compatible Tools

mcp-database works with any tool that supports the MCP protocol. The configuration pattern is the same: point the tool to the mcp-database command and set MCP_DATABASE_URL.

Supported Databases

Database

Status

Install

SQLite

Built-in

pip install mcp-database

PostgreSQL

Optional

pip install 'mcp-database[postgres]'

MySQL

Optional

pip install 'mcp-database[mysql]'

MongoDB

Preview

pip install 'mcp-database[mongodb]'

All

Optional

pip install 'mcp-database[all]'

Configuration

Environment Variables

Variable

Default

Description

MCP_DATABASE_URL

sqlite:///:memory:

Database connection URL

MCP_DATABASE_TYPE

sqlite

Database type: sqlite, postgresql, mysql

MCP_DATABASE_READ_ONLY

true

Enable read-only mode

MCP_MAX_ROWS

100

Maximum rows returned per query

MCP_QUERY_TIMEOUT

30

Query timeout in seconds

MCP_MASK_SENSITIVE

false

Mask sensitive columns (email, phone, token, etc.)

MCP_DATABASE_CONFIG

—

Path to JSON config file for multiple connections

Multiple Connections

To connect to multiple databases simultaneously, create a JSON config file:

{
  "connections": {
    "prod": {"url": "postgres://user:pass@host:5432/db", "read_only": true},
    "staging": {"url": "postgres://user:pass@host:5432/staging", "read_only": true},
    "local": {"url": "sqlite:///dev.db", "read_only": false}
  },
  "settings": {
    "max_rows": 100,
    "allow_writes": false
  }
}

Set MCP_DATABASE_CONFIG to the file path. All tools accept an optional connection_name parameter (defaults to "default").

Connection URLs

# SQLite
MCP_DATABASE_URL=sqlite:///path/to/db.sqlite
MCP_DATABASE_URL=sqlite:///:memory:

# PostgreSQL
MCP_DATABASE_URL=postgres://user:password@localhost:5432/mydb
MCP_DATABASE_TYPE=postgresql

# MySQL
MCP_DATABASE_URL=mysql://user:password@localhost:3306/mydb
MCP_DATABASE_TYPE=mysql

Available Tools

Once connected, Claude can use these tools:

Tool

Description

list_databases

List all configured database connections

list_tables

List all tables in a database

get_table_info

Get detailed table info (columns, types, row count)

get_schema

Get full database schema (CREATE TABLE statements)

query

Execute a read-only SQL query (SELECT, SHOW, DESCRIBE)

execute

Execute a write statement (INSERT, UPDATE, DELETE) — opt-in only

sample_rows

Get sample rows from a table

search_tables

Search for tables or columns by keyword

schema_diff

Compare schemas between two database connections

check_health

Get database health metrics (table count, row counts, latency)

generate_er_diagram

Generate Mermaid ER diagram from database schema

explain_query

Explain the execution plan for a SELECT query

diagnose_connection

Diagnose connection issues with troubleshooting hints

Examples

Ask Claude things like:

  • "What tables are in my database?"

  • "Show me the schema for the users table"

  • "Query the top 10 orders by amount"

  • "Find all columns related to 'email'"

  • "Sample some rows from the products table"

  • "Compare schemas between staging and production"

  • "Generate an ER diagram for my database"

  • "How large are my tables?"

Security

  • Read-only by default — queries are safe, no data modification

  • Write opt-in — set allow_writes=True and MCP_DATABASE_READ_ONLY=false to enable

  • Read-only detection — write tool rejects SELECT statements (use query instead)

  • Row limits — configurable max rows to prevent accidental large result sets

  • Query timeout — configurable timeout (default 30s) to prevent slow queries from blocking

  • Data masking — optionally mask sensitive columns (emails, phones, tokens) with MCP_MASK_SENSITIVE=true

Integration with Mergewall

Use mcp-database as the storage backend for Mergewall audit data:

# 1. Create audit database
MCP_DATABASE_URL=sqlite:///mergewall-audit.db mcp-database

# 2. Ask Claude: "Create the mergewall_audit table using the schema resource"
# 3. Configure Mergewall to export audit data
#    (See Mergewall docs for database export configuration)

This gives you SQL-queryable governance history instead of flat JSONL files.

Development

# Clone and install for development
git clone https://github.com/jovian-zhibai/mcp-database.git
cd mcp-database
pip install -e ".[dev]"

# Run tests
pytest

# Run with Inspector UI
mcp dev src/mcp_database/server.py

License

MIT — see LICENSE.

Available Tools

13 tools
check_healthA

Check database health: latency, table count, row count, largest tables.

Args: connection_name: Name of the database connection (default: "default").

Inputs: connection_name. Returns: result

diagnose_connectionB

Diagnose a database connection with detailed status and troubleshooting hints.

Args: connection_name: Name of the database connection (default: "default").

Inputs: connection_name. Returns: result

executeA

Execute a write SQL statement (INSERT, UPDATE, DELETE). Only works if writes are enabled.

Args: sql: SQL statement to execute. database: Name of the database within the connection (optional). connection_name: Name of the database connection (default: "default").

Inputs: sql (required), database, connection_name. Returns: result

explain_queryA

Explain the execution plan for a SELECT query.

Args: query: SQL SELECT or WITH...SELECT statement to explain. connection_name: Name of the database connection (default: "default").

Inputs: query (required), connection_name. Returns: result

generate_er_diagramA

Generate an ER (Entity-Relationship) diagram in Mermaid format.

Args: connection_name: Name of the database connection (default: "default"). format: Output format. Currently only 'mermaid' is supported.

Inputs: format, connection_name. Returns: result

get_schemaA

Get the full database schema (CREATE TABLE statements for all tables).

Args: database: Name of the database within the connection (optional). connection_name: Name of the database connection (default: "default").

Inputs: database, connection_name. Returns: result

get_table_infoB

Get detailed information about a table: columns, types, row count.

Args: table: Table name. database: Name of the database within the connection (optional). connection_name: Name of the database connection (default: "default").

Inputs: table (required), database, connection_name. Returns: result

list_databasesA

List all configured database connections and their status.

Returns JSON with connection names, types, status, and masked URLs.

Inputs: no named parameters. Returns: result

list_tablesB

List all tables in a database.

Args: database: Name of the database within the connection (optional). connection_name: Name of the database connection (default: "default").

Inputs: database, connection_name. Returns: result

queryA

Execute a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN) and return results.

Args: sql: SQL query to execute. database: Name of the database within the connection (optional). max_rows: Maximum number of rows to return (default: 100). connection_name: Name of the database connection (default: "default").

Inputs: sql (required), database, max_rows, connection_name. Returns: result

sample_rowsB

Get a sample of rows from a table to understand its data.

Args: table: Table name. limit: Number of rows to sample (default: 5, max: 20). database: Name of the database within the connection (optional). connection_name: Name of the database connection (default: "default").

Inputs: table (required), limit, database, connection_name. Returns: result

schema_diffA

Compare schemas between two database connections.

Args: source_connection: Source connection name. target_connection: Target connection name. table_name: Optional table name to diff. If empty, diff all tables.

Inputs: source_connection (required), target_connection (required), table_name. Returns: result

search_tablesB

Search for tables or columns matching a keyword.

Args: keyword: Keyword to search for in table and column names. database: Name of the database within the connection (optional). connection_name: Name of the database connection (default: "default").

Inputs: keyword (required), database, connection_name. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: query vs execute, get_table_info vs get_schema, and search_tables vs sample_rows are all well separated. However, list_databases, check_health, and diagnose_connection all overlap somewhat around connection status and health reporting.

    Naming Consistency4/5

    The majority of tools follow a clear verb_noun pattern such as list_tables, get_schema, sample_rows, and search_tables. Minor deviations include the bare verbs query and execute, plus the noun_noun schema_diff, but these do not seriously harm predictability.

    Tool Count5/5

    With 13 tools, the server is well within the ideal range for a database-focused MCP server. Each tool contributes a distinct capability from schema introspection to querying, health checks, diffs, and ER diagram generation.

    Completeness4/5

    The toolset covers the core database workflow well: listing connections and tables, inspecting schemas, sampling data, running read/write SQL, checking health, and comparing schemas. The main gap is lack of DDL or schema modification operations, though execute could partially cover writes if extended.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • db-mcp-server

      stucchi
      A
      license
      A
      quality
      D
      maintenance
      A multi-database MCP server supporting MySQL, PostgreSQL, MongoDB, and SQLite with read-only and read-write query capabilities, schema inspection, and SSH tunneling, all without Docker.
      5
      57 PyPI
      1
      MIT

    • Raja SQL MCP

      Raja-genai
      A
      license
      C
      quality
      C
      maintenance
      An MCP server for interacting with SQLite databases, enabling SQL query execution, schema inspection, and CRUD operations.
      7
      MIT

    • SQL Database Bridge

      alizaimovic
      A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that connects to SQL databases (SQLite, PostgreSQL, MSSQL, MySQL) and provides tools to run read-only queries, list schemas/tables, and manage connections via stdio transport.
      Apache 2.0

    • sql-mcp

      teghoz
      F
      license
      A
      quality
      D
      maintenance
      A read-only MCP server for SQL Server and PostgreSQL that enables exploring and querying databases (schemas, tables, views, procedures, indexes, foreign keys) and running arbitrary SELECT queries.
      37
      -