mcp-database 0.1.0__py3-none-any.whl

mcp_database/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-database — MCP server for multi-database access."""
+
+__version__ = "0.1.0"

mcp_database/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m mcp_database"""
+
+from mcp_database.server import main
+
+main()

mcp_database/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Database adapters for mcp-database."""
+
+from mcp_database.adapters.base import DatabaseAdapter
+from mcp_database.adapters.sqlite import SQLiteAdapter
+
+__all__ = ["DatabaseAdapter", "SQLiteAdapter"]

mcp_database/adapters/base.py

@@ -0,0 +1,108 @@
+"""Base adapter interface for database connections."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class QueryResult:
+    """Result of a SQL query."""
+
+    columns: list[str]
+    rows: list[list[Any]]
+    row_count: int
+    truncated: bool = False
+
+    def to_table(self, max_rows: int = 100) -> str:
+        """Format result as an aligned text table."""
+        if not self.columns:
+            return "No results."
+
+        rows = self.rows[:max_rows]
+        # Calculate column widths
+        widths = [len(c) for c in self.columns]
+        for row in rows:
+            for i, val in enumerate(row):
+                if i < len(widths):
+                    widths[i] = max(widths[i], len(str(val)))
+
+        # Header
+        header = " | ".join(c.ljust(widths[i]) for i, c in enumerate(self.columns))
+        separator = "-+-".join("-" * w for w in widths)
+        lines = [header, separator]
+
+        # Rows
+        for row in rows:
+            line = " | ".join(str(row[i]).ljust(widths[i]) if i < len(row) else "" for i in range(len(self.columns)))
+            lines.append(line)
+
+        result = "\n".join(lines)
+        if self.truncated:
+            result += f"\n... ({self.row_count} total rows, showing first {max_rows})"
+        return result
+
+
+@dataclass
+class TableInfo:
+    """Information about a database table."""
+
+    name: str
+    columns: list[dict[str, Any]]
+    row_count: int | None = None
+    create_sql: str | None = None
+
+
+class DatabaseAdapter(ABC):
+    """Abstract base class for database adapters."""
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Establish connection to the database."""
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Close the database connection."""
+
+    @abstractmethod
+    def test_connection(self) -> bool:
+        """Test if the connection is alive."""
+
+    @abstractmethod
+    def list_databases(self) -> list[str]:
+        """List available databases (if applicable)."""
+
+    @abstractmethod
+    def list_tables(self, database: str | None = None) -> list[str]:
+        """List all tables in the database."""
+
+    @abstractmethod
+    def get_table_info(self, table: str, database: str | None = None) -> TableInfo:
+        """Get detailed information about a table."""
+
+    @abstractmethod
+    def get_schema(self, database: str | None = None) -> str:
+        """Get the full database schema as formatted text."""
+
+    @abstractmethod
+    def execute_query(self, sql: str, database: str | None = None, max_rows: int = 100) -> QueryResult:
+        """Execute a read-only SQL query."""
+
+    def execute_write(self, sql: str, database: str | None = None) -> int:
+        """Execute a write SQL query (INSERT/UPDATE/DELETE). Returns affected rows.
+
+        Raises NotImplementedError if the adapter is read-only.
+        """
+        raise NotImplementedError("This adapter is read-only. Use execute_query() for SELECT statements.")
+
+    @property
+    @abstractmethod
+    def db_type(self) -> str:
+        """Return the database type name (e.g., 'sqlite', 'postgresql', 'mysql')."""
+
+    def _is_read_only_query(self, sql: str) -> bool:
+        """Check if a query is read-only (SELECT, SHOW, DESCRIBE, EXPLAIN)."""
+        normalized = sql.strip().upper()
+        # Allow SELECT, SHOW, DESCRIBE, EXPLAIN, WITH (CTE leading to SELECT)
+        read_only_prefixes = ("SELECT", "SHOW", "DESCRIBE", "DESC", "EXPLAIN", "WITH", "PRAGMA")
+        return any(normalized.startswith(prefix) for prefix in read_only_prefixes)

mcp_database/adapters/mysql.py

@@ -0,0 +1,173 @@
+"""MySQL database adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp_database.adapters.base import DatabaseAdapter, QueryResult, TableInfo
+
+
+class MySQLAdapter(DatabaseAdapter):
+    """Adapter for MySQL databases."""
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 3306,
+        user: str = "root",
+        password: str = "",
+        database: str = "",
+        read_only: bool = True,
+    ):
+        self.host = host
+        self.port = port
+        self.user = user
+        self.password = password
+        self.default_database = database
+        self.read_only = read_only
+        self._conn: Any = None
+
+    def connect(self) -> None:
+        try:
+            import pymysql
+        except ImportError:
+            raise ImportError(
+                "pymysql is required for MySQL. Install with: pip install 'mcp-database[mysql]'"
+            )
+        self._conn = pymysql.connect(
+            host=self.host,
+            port=self.port,
+            user=self.user,
+            password=self.password,
+            database=self.default_database or None,
+            charset="utf8mb4",
+            cursorclass=pymysql.cursors.DictCursor,
+        )
+        if self.read_only:
+            cur = self._conn.cursor()
+            cur.execute("SET SESSION TRANSACTION READ ONLY")
+            cur.close()
+
+    def disconnect(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def test_connection(self) -> bool:
+        try:
+            if not self._conn:
+                return False
+            cur = self._conn.cursor()
+            cur.execute("SELECT 1")
+            cur.close()
+            return True
+        except Exception:
+            return False
+
+    def list_databases(self) -> list[str]:
+        cur = self._get_conn().cursor()
+        cur.execute("SHOW DATABASES")
+        rows = cur.fetchall()
+        cur.close()
+        return [r["Database"] for r in rows]
+
+    def list_tables(self, database: str | None = None) -> list[str]:
+        conn = self._get_conn()
+        cur = conn.cursor()
+        if database:
+            cur.execute(f"SHOW TABLES FROM `{database}`")
+        else:
+            cur.execute("SHOW TABLES")
+        rows = cur.fetchall()
+        cur.close()
+        # The column name varies: "Tables_in_{database}" or "Tables_in_{current_db}"
+        return [list(r.values())[0] for r in rows]
+
+    def get_table_info(self, table: str, database: str | None = None) -> TableInfo:
+        conn = self._get_conn()
+        cur = conn.cursor()
+
+        table_ref = f"`{database}`.`{table}`" if database else f"`{table}`"
+
+        # Get columns
+        cur.execute(f"DESCRIBE {table_ref}")
+        col_rows = cur.fetchall()
+        columns = [
+            {
+                "name": r["Field"],
+                "type": r["Type"],
+                "nullable": r["Null"] == "YES",
+                "default": r["Default"],
+                "primary_key": r["Key"] == "PRI",
+            }
+            for r in col_rows
+        ]
+
+        # Get row count
+        cur.execute(f"SELECT COUNT(*) as cnt FROM {table_ref}")
+        row_count = cur.fetchone()["cnt"]
+
+        # Get create SQL
+        cur.execute(f"SHOW CREATE TABLE {table_ref}")
+        create_row = cur.fetchone()
+        create_sql = create_row.get("Create Table") if create_row else None
+
+        cur.close()
+        return TableInfo(name=table, columns=columns, row_count=row_count, create_sql=create_sql)
+
+    def get_schema(self, database: str | None = None) -> str:
+        tables = self.list_tables(database)
+        parts = []
+        for table in tables:
+            info = self.get_table_info(table, database)
+            if info.create_sql:
+                parts.append(info.create_sql)
+            else:
+                col_lines = []
+                for col in info.columns:
+                    parts_str = [col["type"]]
+                    if col["primary_key"]:
+                        parts_str.append("PRIMARY KEY")
+                    if not col["nullable"]:
+                        parts_str.append("NOT NULL")
+                    if col["default"] is not None:
+                        parts_str.append(f"DEFAULT {col['default']}")
+                    col_lines.append(f"  {col['name']} {' '.join(parts_str)}")
+                parts.append(f"CREATE TABLE {table} (\n" + ",\n".join(col_lines) + "\n);")
+        return "\n\n".join(parts) if parts else "No tables found."
+
+    def execute_query(self, sql: str, database: str | None = None, max_rows: int = 100) -> QueryResult:
+        conn = self._get_conn()
+        cur = conn.cursor()
+        if database:
+            cur.execute(f"USE `{database}`")
+        cur.execute(sql)
+        columns = [desc[0] for desc in cur.description] if cur.description else []
+        all_rows = cur.fetchall()
+        row_count = len(all_rows)
+        truncated = row_count > max_rows
+        rows = [[row.get(c) for c in columns] for row in all_rows[:max_rows]]
+        cur.close()
+        return QueryResult(columns=columns, rows=rows, row_count=row_count, truncated=truncated)
+
+    def execute_write(self, sql: str, database: str | None = None) -> int:
+        if self.read_only:
+            raise NotImplementedError("MySQL adapter is in read-only mode. Set read_only=False to enable writes.")
+        conn = self._get_conn()
+        cur = conn.cursor()
+        if database:
+            cur.execute(f"USE `{database}`")
+        cur.execute(sql)
+        affected = cur.rowcount
+        conn.commit()
+        cur.close()
+        return affected
+
+    @property
+    def db_type(self) -> str:
+        return "mysql"
+
+    def _get_conn(self) -> Any:
+        if not self._conn:
+            raise RuntimeError("Not connected. Call connect() first.")
+        return self._conn

mcp_database/adapters/postgres.py

@@ -0,0 +1,174 @@
+"""PostgreSQL database adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp_database.adapters.base import DatabaseAdapter, QueryResult, TableInfo
+
+
+class PostgreSQLAdapter(DatabaseAdapter):
+    """Adapter for PostgreSQL databases."""
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 5432,
+        user: str = "postgres",
+        password: str = "",
+        database: str = "postgres",
+        read_only: bool = True,
+    ):
+        self.host = host
+        self.port = port
+        self.user = user
+        self.password = password
+        self.default_database = database
+        self.read_only = read_only
+        self._conn: Any = None
+
+    def connect(self) -> None:
+        try:
+            import psycopg2
+        except ImportError:
+            raise ImportError(
+                "psycopg2 is required for PostgreSQL. Install with: pip install 'mcp-database[postgres]'"
+            )
+        self._conn = psycopg2.connect(
+            host=self.host,
+            port=self.port,
+            user=self.user,
+            password=self.password,
+            dbname=self.default_database,
+        )
+        if self.read_only:
+            self._conn.set_session(readonly=True)
+
+    def disconnect(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def test_connection(self) -> bool:
+        try:
+            if not self._conn:
+                return False
+            cur = self._conn.cursor()
+            cur.execute("SELECT 1")
+            cur.close()
+            return True
+        except Exception:
+            return False
+
+    def list_databases(self) -> list[str]:
+        cur = self._get_conn().cursor()
+        cur.execute("SELECT datname FROM pg_database WHERE datistemplate = false ORDER BY datname")
+        rows = cur.fetchall()
+        cur.close()
+        return [r[0] for r in rows]
+
+    def list_tables(self, database: str | None = None) -> list[str]:
+        cur = self._get_conn().cursor()
+        cur.execute(
+            "SELECT table_name FROM information_schema.tables "
+            "WHERE table_schema = 'public' ORDER BY table_name"
+        )
+        rows = cur.fetchall()
+        cur.close()
+        return [r[0] for r in rows]
+
+    def get_table_info(self, table: str, database: str | None = None) -> TableInfo:
+        conn = self._get_conn()
+        cur = conn.cursor()
+
+        # Get columns
+        cur.execute(
+            "SELECT column_name, data_type, is_nullable, column_default "
+            "FROM information_schema.columns "
+            "WHERE table_schema = 'public' AND table_name = %s "
+            "ORDER BY ordinal_position",
+            (table,),
+        )
+        col_rows = cur.fetchall()
+        columns = [
+            {
+                "name": r[0],
+                "type": r[1],
+                "nullable": r[2] == "YES",
+                "default": r[3],
+                "primary_key": False,  # determined below
+            }
+            for r in col_rows
+        ]
+
+        # Get primary keys
+        cur.execute(
+            "SELECT a.attname FROM pg_index i "
+            "JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey) "
+            "WHERE i.indrelid = %s::regclass AND i.indisprimary",
+            (table,),
+        )
+        pk_cols = {r[0] for r in cur.fetchall()}
+        for col in columns:
+            if col["name"] in pk_cols:
+                col["primary_key"] = True
+
+        # Get row count (estimate for large tables)
+        cur.execute(f"SELECT COUNT(*) FROM \"{table}\"")
+        row_count = cur.fetchone()[0]
+
+        # Get create SQL (PostgreSQL doesn't have a single CREATE TABLE statement)
+        create_sql = None
+
+        cur.close()
+        return TableInfo(name=table, columns=columns, row_count=row_count, create_sql=create_sql)
+
+    def get_schema(self, database: str | None = None) -> str:
+        tables = self.list_tables(database)
+        parts = []
+        for table in tables:
+            info = self.get_table_info(table, database)
+            col_lines = []
+            for col in info.columns:
+                parts_str = [col["type"]]
+                if col["primary_key"]:
+                    parts_str.append("PRIMARY KEY")
+                if not col["nullable"]:
+                    parts_str.append("NOT NULL")
+                if col["default"] is not None:
+                    parts_str.append(f"DEFAULT {col['default']}")
+                col_lines.append(f"  {col['name']} {' '.join(parts_str)}")
+            parts.append(f"CREATE TABLE {table} (\n" + ",\n".join(col_lines) + "\n);")
+        return "\n\n".join(parts) if parts else "No tables found."
+
+    def execute_query(self, sql: str, database: str | None = None, max_rows: int = 100) -> QueryResult:
+        conn = self._get_conn()
+        cur = conn.cursor()
+        cur.execute(sql)
+        columns = [desc[0] for desc in cur.description] if cur.description else []
+        all_rows = cur.fetchall()
+        row_count = len(all_rows)
+        truncated = row_count > max_rows
+        rows = [list(row) for row in all_rows[:max_rows]]
+        cur.close()
+        return QueryResult(columns=columns, rows=rows, row_count=row_count, truncated=truncated)
+
+    def execute_write(self, sql: str, database: str | None = None) -> int:
+        if self.read_only:
+            raise NotImplementedError("PostgreSQL adapter is in read-only mode. Set read_only=False to enable writes.")
+        conn = self._get_conn()
+        cur = conn.cursor()
+        cur.execute(sql)
+        affected = cur.rowcount
+        conn.commit()
+        cur.close()
+        return affected
+
+    @property
+    def db_type(self) -> str:
+        return "postgresql"
+
+    def _get_conn(self) -> Any:
+        if not self._conn:
+            raise RuntimeError("Not connected. Call connect() first.")
+        return self._conn

mcp_database/adapters/sqlite.py

@@ -0,0 +1,120 @@
+"""SQLite database adapter."""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import Any
+
+from mcp_database.adapters.base import DatabaseAdapter, QueryResult, TableInfo
+
+
+class SQLiteAdapter(DatabaseAdapter):
+    """Adapter for SQLite databases."""
+
+    def __init__(self, database_path: str, read_only: bool = True):
+        self.database_path = database_path
+        self.read_only = read_only
+        self._conn: sqlite3.Connection | None = None
+
+    def connect(self) -> None:
+        uri = f"file:{self.database_path}"
+        if self.read_only:
+            uri += "?mode=ro"
+        self._conn = sqlite3.connect(uri, uri=True)
+        self._conn.row_factory = sqlite3.Row
+
+    def disconnect(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def test_connection(self) -> bool:
+        try:
+            if not self._conn:
+                return False
+            self._conn.execute("SELECT 1")
+            return True
+        except Exception:
+            return False
+
+    def list_databases(self) -> list[str]:
+        return ["main"]
+
+    def list_tables(self, database: str | None = None) -> list[str]:
+        conn = self._get_conn()
+        rows = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        ).fetchall()
+        return [r["name"] for r in rows]
+
+    def get_table_info(self, table: str, database: str | None = None) -> TableInfo:
+        conn = self._get_conn()
+        # Get column info
+        columns_raw = conn.execute(f"PRAGMA table_info('{table}')").fetchall()
+        columns = [
+            {
+                "name": r["name"],
+                "type": r["type"],
+                "nullable": not r["notnull"],
+                "default": r["dflt_value"],
+                "primary_key": bool(r["pk"]),
+            }
+            for r in columns_raw
+        ]
+
+        # Get row count
+        row_count = conn.execute(f"SELECT COUNT(*) as cnt FROM '{table}'").fetchone()["cnt"]
+
+        # Get create SQL
+        create_row = conn.execute(
+            "SELECT sql FROM sqlite_master WHERE type='table' AND name=?", (table,)
+        ).fetchone()
+        create_sql = create_row["sql"] if create_row else None
+
+        return TableInfo(name=table, columns=columns, row_count=row_count, create_sql=create_sql)
+
+    def get_schema(self, database: str | None = None) -> str:
+        conn = self._get_conn()
+        tables = self.list_tables()
+        parts = []
+        for table in tables:
+            info = self.get_table_info(table)
+            col_lines = []
+            for col in info.columns:
+                parts_str = [col["type"]]
+                if col["primary_key"]:
+                    parts_str.append("PRIMARY KEY")
+                if not col["nullable"]:
+                    parts_str.append("NOT NULL")
+                if col["default"] is not None:
+                    parts_str.append(f"DEFAULT {col['default']}")
+                col_lines.append(f"  {col['name']} {' '.join(parts_str)}")
+            parts.append(f"CREATE TABLE {table} (\n" + ",\n".join(col_lines) + "\n);")
+        return "\n\n".join(parts) if parts else "No tables found."
+
+    def execute_query(self, sql: str, database: str | None = None, max_rows: int = 100) -> QueryResult:
+        conn = self._get_conn()
+        cursor = conn.execute(sql)
+        columns = [desc[0] for desc in cursor.description] if cursor.description else []
+        all_rows = cursor.fetchall()
+        row_count = len(all_rows)
+        truncated = row_count > max_rows
+        rows = [list(row) for row in all_rows[:max_rows]]
+        return QueryResult(columns=columns, rows=rows, row_count=row_count, truncated=truncated)
+
+    def execute_write(self, sql: str, database: str | None = None) -> int:
+        if self.read_only:
+            raise NotImplementedError("SQLite adapter is in read-only mode. Set read_only=False to enable writes.")
+        conn = self._get_conn()
+        cursor = conn.execute(sql)
+        conn.commit()
+        return cursor.rowcount
+
+    @property
+    def db_type(self) -> str:
+        return "sqlite"
+
+    def _get_conn(self) -> sqlite3.Connection:
+        if not self._conn:
+            raise RuntimeError("Not connected. Call connect() first.")
+        return self._conn

mcp_database/config.py

@@ -0,0 +1,120 @@
+"""Configuration for mcp-database server."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DatabaseConfig:
+    """Configuration for a single database connection."""
+
+    name: str
+    type: str  # sqlite, postgresql, mysql
+    # SQLite
+    path: str = ""
+    # PostgreSQL / MySQL
+    host: str = "localhost"
+    port: int = 0
+    user: str = ""
+    password: str = ""
+    database: str = ""
+    # Options
+    read_only: bool = True
+
+    def __post_init__(self) -> None:
+        if self.type == "sqlite" and not self.path:
+            raise ValueError(f"Database '{self.name}': 'path' is required for SQLite")
+        if self.type in ("postgresql", "mysql") and not self.host:
+            raise ValueError(f"Database '{self.name}': 'host' is required for {self.type}")
+
+
+@dataclass
+class ServerConfig:
+    """Server-level configuration."""
+
+    databases: list[DatabaseConfig] = field(default_factory=list)
+    max_rows: int = 100
+    allow_writes: bool = False
+
+
+def load_config_from_env() -> ServerConfig:
+    """Load configuration from environment variables.
+
+    Supports:
+        MCP_DATABASE_URL - single database URL (sqlite:///path or postgres://...)
+        MCP_DATABASE_TYPE - database type (default: sqlite)
+        MCP_DATABASE_READ_ONLY - read-only mode (default: true)
+        MCP_MAX_ROWS - max rows to return (default: 100)
+    """
+    db_url = os.environ.get("MCP_DATABASE_URL", "")
+    db_type = os.environ.get("MCP_DATABASE_TYPE", "sqlite")
+    read_only = os.environ.get("MCP_DATABASE_READ_ONLY", "true").lower() in ("true", "1", "yes")
+    max_rows = int(os.environ.get("MCP_MAX_ROWS", "100"))
+
+    if db_url:
+        config = _parse_url_to_config(db_url, db_type, read_only)
+        return ServerConfig(databases=[config], max_rows=max_rows, allow_writes=not read_only)
+
+    # Default: in-memory SQLite for demo/testing
+    return ServerConfig(
+        databases=[
+            DatabaseConfig(name="demo", type="sqlite", path=":memory:", read_only=False)
+        ],
+        max_rows=max_rows,
+    )
+
+
+def load_config_from_dict(data: dict) -> ServerConfig:
+    """Load configuration from a dictionary (e.g., parsed YAML)."""
+    databases = []
+    for db_data in data.get("databases", []):
+        databases.append(DatabaseConfig(**db_data))
+    return ServerConfig(
+        databases=databases,
+        max_rows=data.get("max_rows", 100),
+        allow_writes=data.get("allow_writes", False),
+    )
+
+
+def _parse_url_to_config(url: str, db_type: str, read_only: bool) -> DatabaseConfig:
+    """Parse a database URL into a DatabaseConfig."""
+    if db_type == "sqlite":
+        # sqlite:///path/to/db.sqlite or sqlite:///:memory:
+        path = url.replace("sqlite:///", "").replace("sqlite://", "")
+        return DatabaseConfig(name="main", type="sqlite", path=path, read_only=read_only)
+
+    if db_type == "postgresql":
+        # postgres://user:password@host:port/database
+        from urllib.parse import urlparse
+
+        parsed = urlparse(url)
+        return DatabaseConfig(
+            name="main",
+            type="postgresql",
+            host=parsed.hostname or "localhost",
+            port=parsed.port or 5432,
+            user=parsed.username or "postgres",
+            password=parsed.password or "",
+            database=parsed.path.lstrip("/") or "postgres",
+            read_only=read_only,
+        )
+
+    if db_type == "mysql":
+        # mysql://user:password@host:port/database
+        from urllib.parse import urlparse
+
+        parsed = urlparse(url)
+        return DatabaseConfig(
+            name="main",
+            type="mysql",
+            host=parsed.hostname or "localhost",
+            port=parsed.port or 3306,
+            user=parsed.username or "root",
+            password=parsed.password or "",
+            database=parsed.path.lstrip("/") or "",
+            read_only=read_only,
+        )
+
+    raise ValueError(f"Unsupported database type: {db_type}")

mcp_database/server.py

@@ -0,0 +1,285 @@
+"""mcp-database — MCP server for multi-database access.
+
+Provides tools for Claude to query, inspect, and manage databases
+(SQLite, PostgreSQL, MySQL) through the Model Context Protocol.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+
+from mcp.server.fastmcp import Context, FastMCP
+
+from mcp_database.adapters.base import DatabaseAdapter
+from mcp_database.adapters.sqlite import SQLiteAdapter
+from mcp_database.config import ServerConfig, load_config_from_env
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Adapter factory
+# ---------------------------------------------------------------------------
+
+def _create_adapter(config) -> DatabaseAdapter:
+    """Create a database adapter from config."""
+    if config.type == "sqlite":
+        return SQLiteAdapter(database_path=config.path, read_only=config.read_only)
+    if config.type == "postgresql":
+        from mcp_database.adapters.postgres import PostgreSQLAdapter
+
+        return PostgreSQLAdapter(
+            host=config.host,
+            port=config.port or 5432,
+            user=config.user,
+            password=config.password,
+            database=config.database,
+            read_only=config.read_only,
+        )
+    if config.type == "mysql":
+        from mcp_database.adapters.mysql import MySQLAdapter
+
+        return MySQLAdapter(
+            host=config.host,
+            port=config.port or 3306,
+            user=config.user,
+            password=config.password,
+            database=config.database,
+            read_only=config.read_only,
+        )
+    raise ValueError(f"Unsupported database type: {config.type}")
+
+
+# ---------------------------------------------------------------------------
+# Lifespan context
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AppContext:
+    adapters: dict[str, DatabaseAdapter] = field(default_factory=dict)
+    config: ServerConfig = field(default_factory=ServerConfig)
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
+    """Manage database connections on server startup/shutdown."""
+    config = load_config_from_env()
+    adapters: dict[str, DatabaseAdapter] = {}
+
+    for db_config in config.databases:
+        adapter = _create_adapter(db_config)
+        try:
+            adapter.connect()
+            adapters[db_config.name] = adapter
+            logger.info("Connected to %s (%s)", db_config.name, db_config.type)
+        except Exception:
+            logger.exception("Failed to connect to %s", db_config.name)
+
+    try:
+        yield AppContext(adapters=adapters, config=config)
+    finally:
+        for name, adapter in adapters.items():
+            try:
+                adapter.disconnect()
+                logger.info("Disconnected from %s", name)
+            except Exception:
+                logger.exception("Error disconnecting from %s", name)
+
+
+# ---------------------------------------------------------------------------
+# MCP Server
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP(
+    "Database Server",
+    version="0.1.0",
+    lifespan=app_lifespan,
+)
+
+
+def _get_adapter(ctx: Context, name: str | None = None) -> DatabaseAdapter:
+    """Get a database adapter by name, or the first one if name is None."""
+    app_ctx: AppContext = ctx.request_context.lifespan_context
+    if not app_ctx.adapters:
+        raise RuntimeError("No databases configured.")
+    if name:
+        if name not in app_ctx.adapters:
+            available = ", ".join(app_ctx.adapters.keys())
+            raise ValueError(f"Database '{name}' not found. Available: {available}")
+        return app_ctx.adapters[name]
+    return next(iter(app_ctx.adapters.values()))
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def list_databases(ctx: Context) -> str:
+    """List all configured database connections and their types."""
+    app_ctx: AppContext = ctx.request_context.lifespan_context
+    lines = []
+    for name, adapter in app_ctx.adapters.items():
+        status = "connected" if adapter.test_connection() else "disconnected"
+        lines.append(f"{name} ({adapter.db_type}) — {status}")
+    return "\n".join(lines) if lines else "No databases configured."
+
+
+@mcp.tool()
+def list_tables(database: str | None = None, ctx: Context = None) -> str:
+    """List all tables in a database.
+
+    Args:
+        database: Name of the database connection (optional if only one is configured).
+    """
+    adapter = _get_adapter(ctx, database)
+    tables = adapter.list_tables()
+    if not tables:
+        return f"No tables found in {database or adapter.db_type}."
+    return "\n".join(tables)
+
+
+@mcp.tool()
+def get_table_info(table: str, database: str | None = None, ctx: Context = None) -> str:
+    """Get detailed information about a table: columns, types, row count.
+
+    Args:
+        table: Table name.
+        database: Name of the database connection (optional if only one is configured).
+    """
+    adapter = _get_adapter(ctx, database)
+    info = adapter.get_table_info(table)
+
+    lines = [f"Table: {info.name}", f"Rows: {info.row_count}", "", "Columns:"]
+    for col in info.columns:
+        parts = [col["name"], col["type"]]
+        if col["primary_key"]:
+            parts.append("PK")
+        if not col["nullable"]:
+            parts.append("NOT NULL")
+        if col["default"] is not None:
+            parts.append(f"DEFAULT {col['default']}")
+        lines.append(f"  {' '.join(parts)}")
+
+    if info.create_sql:
+        lines.extend(["", "CREATE SQL:", info.create_sql])
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_schema(database: str | None = None, ctx: Context = None) -> str:
+    """Get the full database schema (CREATE TABLE statements for all tables).
+
+    Args:
+        database: Name of the database connection (optional if only one is configured).
+    """
+    adapter = _get_adapter(ctx, database)
+    return adapter.get_schema()
+
+
+@mcp.tool()
+def query(sql: str, database: str | None = None, max_rows: int = 100, ctx: Context = None) -> str:
+    """Execute a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN) and return results.
+
+    Args:
+        sql: SQL query to execute.
+        database: Name of the database connection (optional if only one is configured).
+        max_rows: Maximum number of rows to return (default: 100).
+    """
+    adapter = _get_adapter(ctx, database)
+    app_ctx: AppContext = ctx.request_context.lifespan_context
+    max_rows = min(max_rows, app_ctx.config.max_rows)
+
+    result = adapter.execute_query(sql, max_rows=max_rows)
+    return result.to_table(max_rows=max_rows)
+
+
+@mcp.tool()
+def execute(sql: str, database: str | None = None, ctx: Context = None) -> str:
+    """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 connection (optional if only one is configured).
+    """
+    adapter = _get_adapter(ctx, database)
+    app_ctx: AppContext = ctx.request_context.lifespan_context
+
+    if not app_ctx.config.allow_writes:
+        return "Error: Write operations are disabled. Set allow_writes=True in config to enable."
+
+    if adapter._is_read_only_query(sql):
+        return "Error: Use the 'query' tool for SELECT statements."
+
+    affected = adapter.execute_write(sql)
+    return f"OK. {affected} row(s) affected."
+
+
+@mcp.tool()
+def sample_rows(table: str, limit: int = 5, database: str | None = None, ctx: Context = None) -> str:
+    """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 connection (optional if only one is configured).
+    """
+    adapter = _get_adapter(ctx, database)
+    limit = min(limit, 20)
+    result = adapter.execute_query(f"SELECT * FROM \"{table}\" LIMIT {limit}", max_rows=limit)
+    return result.to_table(max_rows=limit)
+
+
+@mcp.tool()
+def search_tables(keyword: str, database: str | None = None, ctx: Context = None) -> str:
+    """Search for tables or columns matching a keyword.
+
+    Args:
+        keyword: Keyword to search for in table and column names.
+        database: Name of the database connection (optional if only one is configured).
+    """
+    adapter = _get_adapter(ctx, database)
+    keyword_lower = keyword.lower()
+    matches = []
+
+    for table_name in adapter.list_tables():
+        if keyword_lower in table_name.lower():
+            matches.append(f"Table: {table_name}")
+
+        info = adapter.get_table_info(table_name)
+        for col in info.columns:
+            if keyword_lower in col["name"].lower():
+                matches.append(f"  {table_name}.{col['name']} ({col['type']})")
+
+    return "\n".join(matches) if matches else f"No matches for '{keyword}'."
+
+
+# ---------------------------------------------------------------------------
+# Resources
+# ---------------------------------------------------------------------------
+
+@mcp.resource("db://databases")
+def resource_databases(ctx: Context) -> str:
+    """List all configured databases."""
+    app_ctx: AppContext = ctx.request_context.lifespan_context
+    lines = []
+    for name, adapter in app_ctx.adapters.items():
+        lines.append(f"- {name} ({adapter.db_type})")
+    return "\n".join(lines) if lines else "No databases configured."
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    """Run the MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

mcp_database-0.1.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: mcp-database
+Version: 0.1.0
+Summary: MCP server for multi-database access — SQLite, PostgreSQL, MySQL. Query, inspect schema, and manage databases through Claude.
+Author: Mergewall Team
+License: MIT
+License-File: LICENSE
+Keywords: claude,database,mcp,model-context-protocol,mysql,postgresql,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: psycopg2-binary>=2.9.0; extra == 'all'
+Requires-Dist: pymysql>=1.1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1.0; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9.0; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# mcp-database
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-orange)](https://modelcontextprotocol.io)
+
+**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 |
+
+## Quick Start
+
+```bash
+# Install
+pip install mcp-database
+
+# Run with a SQLite database
+MCP_DATABASE_URL=sqlite:///path/to/your.db mcp-database
+```
+
+### Claude Code Integration
+
+```bash
+# 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`:
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "mcp-database",
+      "env": {
+        "MCP_DATABASE_URL": "sqlite:///path/to/your.db"
+      }
+    }
+  }
+}
+```
+
+## 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]'` |
+| **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 |
+
+### Connection URLs
+
+```bash
+# 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 |
+
+## 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"
+
+## 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
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/Jansen003/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](LICENSE).

mcp_database-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+mcp_database/__init__.py,sha256=bwWl9Arr7k4fU1mwQjneoOjKiGSilKzXUGEmbdIVV_4,84
+mcp_database/__main__.py,sha256=5KjDHbkEGU5KzjggDpdI0sFDzr5zBtKOZB8EEesZl5Y,93
+mcp_database/config.py,sha256=hxwqzYm_uuQS3q9_bxTGQAaeefFjNFWeBsP3-p3ogKg,3967
+mcp_database/server.py,sha256=VIgUz_AzESxXCejMxXgfqL6E21nmxzhjJExkVqerZaM,9974
+mcp_database/adapters/__init__.py,sha256=Rjo79cBgm6nk20FZlT-L1ShN-74C4CJQtWlNFHRz_kE,201
+mcp_database/adapters/base.py,sha256=Ga2dykLUskYcdmERSboy6d52cusBjEszhGgbaf7AG2s,3562
+mcp_database/adapters/mysql.py,sha256=gM7MxvFOAqTahdl9MqqdPuL-IgK27QMzfNNQoKixLfE,5821
+mcp_database/adapters/postgres.py,sha256=C0DUm90Q2tAeVTLBqWWfcE7z1AqbBWV9ycHPneXFjZQ,5892
+mcp_database/adapters/sqlite.py,sha256=OLuV9HPMy4jhZRwb70FwLb416v7kCwU6I55a3pe3Z2s,4339
+mcp_database-0.1.0.dist-info/METADATA,sha256=3r47W2LP_OD8Vyh-2PTrjn2Ttmy_JMlMtgdRq8o8E3k,5320
+mcp_database-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mcp_database-0.1.0.dist-info/entry_points.txt,sha256=b3-EncwQwV8PjQeHSs2bt6EAbiCgDTUE_9vhonSgyX4,58
+mcp_database-0.1.0.dist-info/licenses/LICENSE,sha256=UGM1IQ7xoSg6FMJ8S97NOZNSUCXK_n8S2CGQZZgyYNs,1071
+mcp_database-0.1.0.dist-info/RECORD,,

mcp_database-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_database-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-database = mcp_database.server:main

mcp_database-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mergewall Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.