db-mcp-server 1.0.0__tar.gz

db_mcp_server-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ing. Luca Stucchi
+
+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.

db_mcp_server-1.0.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: db-mcp-server
+Version: 1.0.0
+Summary: MCP server for MySQL and MongoDB databases — one instance per database, no Docker required
+Author: Ing. Luca Stucchi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/stucchi/db-mcp-server
+Project-URL: Repository, https://github.com/stucchi/db-mcp-server
+Project-URL: Issues, https://github.com/stucchi/db-mcp-server/issues
+Keywords: mcp,database,mysql,mongodb,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]
+Requires-Dist: aiomysql
+Requires-Dist: motor
+Dynamic: license-file
+
+# db-mcp-server
+
+MCP server for MySQL and MongoDB databases. One instance per database, no Docker required.
+
+## Installation
+
+```bash
+uvx db-mcp-server
+```
+
+## Configuration
+
+Configure via environment variables. Each instance connects to a single database.
+
+### MySQL
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DB_TYPE` | Yes | — | `mysql` |
+| `DB_DATABASE` | Yes | — | Database name |
+| `DB_PASSWORD` | Yes | — | Password |
+| `DB_HOST` | No | `localhost` | Host |
+| `DB_PORT` | No | `3306` | Port |
+| `DB_USER` | No | `root` | User |
+| `DB_MODE` | No | `read-only` | `read-only` or `read-write` |
+
+### MongoDB
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DB_TYPE` | Yes | — | `mongodb` |
+| `DB_DATABASE` | Yes | — | Database name |
+| `DB_URL` | Yes | — | Connection URL (`mongodb://...`) |
+| `DB_MODE` | No | `read-only` | `read-only` or `read-write` |
+
+## Usage in .mcp.json
+
+```json
+{
+  "mcpServers": {
+    "db-prod": {
+      "command": "uvx",
+      "args": ["db-mcp-server"],
+      "env": {
+        "DB_TYPE": "mysql",
+        "DB_MODE": "read-only",
+        "DB_HOST": "db.example.com",
+        "DB_PORT": "3306",
+        "DB_USER": "root",
+        "DB_PASSWORD": "secret",
+        "DB_DATABASE": "myapp"
+      }
+    }
+  }
+}
+```
+
+For multiple databases, add multiple instances:
+
+```json
+{
+  "mcpServers": {
+    "db-prod": {
+      "command": "uvx",
+      "args": ["db-mcp-server"],
+      "env": { "DB_TYPE": "mysql", "DB_DATABASE": "prod", "..." : "..." }
+    },
+    "db-staging": {
+      "command": "uvx",
+      "args": ["db-mcp-server"],
+      "env": { "DB_TYPE": "mongodb", "DB_DATABASE": "staging", "..." : "..." }
+    }
+  }
+}
+```
+
+## Tools
+
+### MySQL
+
+- **query** — Execute read-only SQL (SELECT, SHOW, DESCRIBE, EXPLAIN, WITH)
+- **execute** — Execute write SQL (INSERT, UPDATE, DELETE) — requires `DB_MODE=read-write`
+- **describe** — Describe table structure
+- **list_tables** — List all tables
+- **status** — Show connection info
+
+### MongoDB
+
+- **query** — Find documents in a collection
+- **describe** — Collection stats ($collStats)
+- **list_collections** — List all collections
+- **aggregate** — Execute aggregation pipelines ($out/$merge blocked on read-only)
+- **status** — Show connection info
+
+## License
+
+MIT

db_mcp_server-1.0.0/README.md

@@ -0,0 +1,97 @@
+# db-mcp-server
+
+MCP server for MySQL and MongoDB databases. One instance per database, no Docker required.
+
+## Installation
+
+```bash
+uvx db-mcp-server
+```
+
+## Configuration
+
+Configure via environment variables. Each instance connects to a single database.
+
+### MySQL
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DB_TYPE` | Yes | — | `mysql` |
+| `DB_DATABASE` | Yes | — | Database name |
+| `DB_PASSWORD` | Yes | — | Password |
+| `DB_HOST` | No | `localhost` | Host |
+| `DB_PORT` | No | `3306` | Port |
+| `DB_USER` | No | `root` | User |
+| `DB_MODE` | No | `read-only` | `read-only` or `read-write` |
+
+### MongoDB
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DB_TYPE` | Yes | — | `mongodb` |
+| `DB_DATABASE` | Yes | — | Database name |
+| `DB_URL` | Yes | — | Connection URL (`mongodb://...`) |
+| `DB_MODE` | No | `read-only` | `read-only` or `read-write` |
+
+## Usage in .mcp.json
+
+```json
+{
+  "mcpServers": {
+    "db-prod": {
+      "command": "uvx",
+      "args": ["db-mcp-server"],
+      "env": {
+        "DB_TYPE": "mysql",
+        "DB_MODE": "read-only",
+        "DB_HOST": "db.example.com",
+        "DB_PORT": "3306",
+        "DB_USER": "root",
+        "DB_PASSWORD": "secret",
+        "DB_DATABASE": "myapp"
+      }
+    }
+  }
+}
+```
+
+For multiple databases, add multiple instances:
+
+```json
+{
+  "mcpServers": {
+    "db-prod": {
+      "command": "uvx",
+      "args": ["db-mcp-server"],
+      "env": { "DB_TYPE": "mysql", "DB_DATABASE": "prod", "..." : "..." }
+    },
+    "db-staging": {
+      "command": "uvx",
+      "args": ["db-mcp-server"],
+      "env": { "DB_TYPE": "mongodb", "DB_DATABASE": "staging", "..." : "..." }
+    }
+  }
+}
+```
+
+## Tools
+
+### MySQL
+
+- **query** — Execute read-only SQL (SELECT, SHOW, DESCRIBE, EXPLAIN, WITH)
+- **execute** — Execute write SQL (INSERT, UPDATE, DELETE) — requires `DB_MODE=read-write`
+- **describe** — Describe table structure
+- **list_tables** — List all tables
+- **status** — Show connection info
+
+### MongoDB
+
+- **query** — Find documents in a collection
+- **describe** — Collection stats ($collStats)
+- **list_collections** — List all collections
+- **aggregate** — Execute aggregation pipelines ($out/$merge blocked on read-only)
+- **status** — Show connection info
+
+## License
+
+MIT

db_mcp_server-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=75.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "db-mcp-server"
+version = "1.0.0"
+description = "MCP server for MySQL and MongoDB databases — one instance per database, no Docker required"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Ing. Luca Stucchi" },
+]
+keywords = ["mcp", "database", "mysql", "mongodb", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+]
+dependencies = [
+    "mcp[cli]",
+    "aiomysql",
+    "motor",
+]
+
+[project.urls]
+Homepage = "https://github.com/stucchi/db-mcp-server"
+Repository = "https://github.com/stucchi/db-mcp-server"
+Issues = "https://github.com/stucchi/db-mcp-server/issues"
+
+[project.scripts]
+db-mcp-server = "db_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

db_mcp_server-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

db_mcp_server-1.0.0/src/db_mcp/__main__.py

@@ -0,0 +1,3 @@
+from db_mcp.server import main
+
+main()

db_mcp_server-1.0.0/src/db_mcp/config.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Config:
+    db_type: str  # "mysql" or "mongodb"
+    db_mode: str  # "read-only" or "read-write"
+    db_database: str
+
+    # MySQL
+    db_host: str
+    db_port: int
+    db_user: str
+    db_password: str
+
+    # MongoDB
+    db_url: str
+
+    @property
+    def is_mysql(self) -> bool:
+        return self.db_type == "mysql"
+
+    @property
+    def is_mongodb(self) -> bool:
+        return self.db_type == "mongodb"
+
+    @property
+    def is_read_only(self) -> bool:
+        return self.db_mode == "read-only"
+
+    @staticmethod
+    def from_env() -> Config:
+        db_type = os.environ.get("DB_TYPE", "").lower()
+        db_mode = os.environ.get("DB_MODE", "read-only").lower()
+        db_database = os.environ.get("DB_DATABASE", "")
+
+        missing: list[str] = []
+
+        if db_type not in ("mysql", "mongodb"):
+            raise RuntimeError(
+                "DB_TYPE must be 'mysql' or 'mongodb'.\n"
+                "Set DB_TYPE in your environment variables."
+            )
+
+        if not db_database:
+            missing.append("DB_DATABASE")
+
+        if db_mode not in ("read-only", "read-write"):
+            raise RuntimeError(
+                "DB_MODE must be 'read-only' or 'read-write'.\n"
+                f"Got: '{db_mode}'"
+            )
+
+        # MySQL-specific
+        db_host = os.environ.get("DB_HOST", "localhost")
+        db_port = int(os.environ.get("DB_PORT", "3306"))
+        db_user = os.environ.get("DB_USER", "root")
+        db_password = os.environ.get("DB_PASSWORD", "")
+        db_url = os.environ.get("DB_URL", "")
+
+        if db_type == "mysql" and not db_password:
+            missing.append("DB_PASSWORD")
+
+        if db_type == "mongodb" and not db_url:
+            missing.append("DB_URL")
+
+        if missing:
+            raise RuntimeError(
+                f"Missing required environment variables: {', '.join(missing)}.\n"
+                "MySQL requires: DB_TYPE, DB_DATABASE, DB_PASSWORD\n"
+                "MongoDB requires: DB_TYPE, DB_DATABASE, DB_URL"
+            )
+
+        return Config(
+            db_type=db_type,
+            db_mode=db_mode,
+            db_database=db_database,
+            db_host=db_host,
+            db_port=db_port,
+            db_user=db_user,
+            db_password=db_password,
+            db_url=db_url,
+        )
+
+
+_config: Config | None = None
+
+
+def get_config() -> Config:
+    global _config
+    if _config is None:
+        _config = Config.from_env()
+    return _config

db_mcp_server-1.0.0/src/db_mcp/connection.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import aiomysql
+import motor.motor_asyncio
+
+from db_mcp.config import Config
+
+
+class Connection:
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self._pool: aiomysql.Pool | None = None
+        self._mongo_client: motor.motor_asyncio.AsyncIOMotorClient | None = None
+        self._mongo_db: Any = None
+
+    @property
+    def pool(self) -> aiomysql.Pool:
+        assert self._pool is not None, "MySQL pool not initialized"
+        return self._pool
+
+    @property
+    def db(self) -> Any:
+        assert self._mongo_db is not None, "MongoDB database not initialized"
+        return self._mongo_db
+
+    async def connect(self) -> None:
+        if self.config.is_mysql:
+            await self._connect_mysql()
+        else:
+            await self._connect_mongodb()
+
+    async def _connect_mysql(self) -> None:
+        print(
+            f"[db-mcp] Connecting to MySQL {self.config.db_host}:{self.config.db_port}"
+            f"/{self.config.db_database} ({self.config.db_mode})...",
+            file=sys.stderr,
+        )
+        self._pool = await aiomysql.create_pool(
+            host=self.config.db_host,
+            port=self.config.db_port,
+            user=self.config.db_user,
+            password=self.config.db_password,
+            db=self.config.db_database,
+            autocommit=True,
+        )
+        # Verify connectivity
+        async with self._pool.acquire() as conn:
+            await conn.ping()
+        print("[db-mcp] MySQL connected.", file=sys.stderr)
+
+    async def _connect_mongodb(self) -> None:
+        print(
+            f"[db-mcp] Connecting to MongoDB {self.config.db_database} "
+            f"({self.config.db_mode})...",
+            file=sys.stderr,
+        )
+        self._mongo_client = motor.motor_asyncio.AsyncIOMotorClient(self.config.db_url)
+        self._mongo_db = self._mongo_client[self.config.db_database]
+        # Verify connectivity
+        await self._mongo_db.command("ping")
+        print("[db-mcp] MongoDB connected.", file=sys.stderr)
+
+    async def close(self) -> None:
+        if self._pool is not None:
+            self._pool.close()
+            await self._pool.wait_closed()
+            print("[db-mcp] MySQL disconnected.", file=sys.stderr)
+        if self._mongo_client is not None:
+            self._mongo_client.close()
+            print("[db-mcp] MongoDB disconnected.", file=sys.stderr)

db_mcp_server-1.0.0/src/db_mcp/server.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Annotated, Any
+
+from mcp.server.fastmcp import FastMCP
+
+from db_mcp.config import get_config
+from db_mcp.connection import Connection
+from db_mcp.tools.aggregate import aggregate_mongodb
+from db_mcp.tools.describe import describe_mongodb, describe_mysql
+from db_mcp.tools.execute import execute_mysql
+from db_mcp.tools.list_collections import list_collections as _list_collections
+from db_mcp.tools.list_tables import list_tables as _list_tables
+from db_mcp.tools.query import query_mongodb, query_mysql
+from db_mcp.tools.status import get_status
+
+config = get_config()
+_conn = Connection(config)
+
+
+def _format(result: Any) -> str:
+    return json.dumps(result, indent=2, ensure_ascii=False, default=str)
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[None]:
+    await _conn.connect()
+    try:
+        yield
+    finally:
+        await _conn.close()
+
+
+mcp = FastMCP(
+    f"db-mcp-server ({config.db_type}:{config.db_database})",
+    lifespan=app_lifespan,
+)
+
+
+# --- Tool: query ---
+
+if config.is_mysql:
+
+    @mcp.tool()
+    async def query(
+        query: Annotated[str, "SQL SELECT query to execute"],
+    ) -> str:
+        """Execute a read-only query on the MySQL database. Only SELECT, SHOW, DESCRIBE, EXPLAIN, WITH are allowed on read-only databases."""
+        rows = await query_mysql(_conn, config, query)
+        return _format(rows)
+
+else:
+
+    @mcp.tool()
+    async def query(
+        collection: Annotated[str, "Collection name to query"],
+        filter: Annotated[dict | None, "MongoDB filter object (default: {})"] = None,
+        limit: Annotated[int, "Maximum number of results (default: 100, max: 1000)"] = 100,
+    ) -> str:
+        """Execute a find query on a MongoDB collection."""
+        rows = await query_mongodb(_conn, collection, filter, limit)
+        return _format(rows)
+
+
+# --- Tool: execute (MySQL only) ---
+
+if config.is_mysql:
+
+    @mcp.tool()
+    async def execute(
+        query: Annotated[str, "SQL query to execute (INSERT, UPDATE, DELETE, etc.)"],
+    ) -> str:
+        """Execute a write query on the MySQL database. Only works if the database is configured with mode='read-write'."""
+        result = await execute_mysql(_conn, config, query)
+        return _format(result)
+
+
+# --- Tool: describe ---
+
+if config.is_mysql:
+
+    @mcp.tool()
+    async def describe(
+        table: Annotated[str, "Table name to describe"],
+    ) -> str:
+        """Describe the structure of a MySQL table (DESCRIBE)."""
+        rows = await describe_mysql(_conn, table)
+        return _format(rows)
+
+else:
+
+    @mcp.tool()
+    async def describe(
+        collection: Annotated[str, "Collection name to describe"],
+    ) -> str:
+        """Describe the structure of a MongoDB collection ($collStats)."""
+        rows = await describe_mongodb(_conn, collection)
+        return _format(rows)
+
+
+# --- Tool: list_tables (MySQL only) ---
+
+if config.is_mysql:
+
+    @mcp.tool()
+    async def list_tables() -> str:
+        """List all tables in the MySQL database."""
+        rows = await _list_tables(_conn)
+        return _format(rows)
+
+
+# --- Tool: list_collections (MongoDB only) ---
+
+if config.is_mongodb:
+
+    @mcp.tool()
+    async def list_collections() -> str:
+        """List all collections in the MongoDB database."""
+        names = await _list_collections(_conn)
+        return _format(names)
+
+
+# --- Tool: aggregate (MongoDB only) ---
+
+if config.is_mongodb:
+
+    @mcp.tool()
+    async def aggregate(
+        collection: Annotated[str, "Collection name to aggregate"],
+        pipeline: Annotated[list[dict[str, Any]], "MongoDB aggregation pipeline array"],
+    ) -> str:
+        """Execute an aggregation pipeline on a MongoDB collection. Pipelines with $out/$merge are blocked on read-only databases."""
+        rows = await aggregate_mongodb(_conn, config, collection, pipeline)
+        return _format(rows)
+
+
+# --- Tool: status ---
+
+
+@mcp.tool()
+async def status() -> str:
+    """Show connection info: type, host, database, mode, status."""
+    return _format(get_status(config))
+
+
+def main() -> None:
+    mcp.run(transport="stdio")

db_mcp_server-1.0.0/src/db_mcp/tools/aggregate.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+from db_mcp.config import Config
+from db_mcp.connection import Connection
+from db_mcp.validation import sanitize_table_name, validate_aggregate_pipeline
+
+
+async def aggregate_mongodb(
+    conn: Connection,
+    config: Config,
+    collection: str,
+    pipeline: list[dict[str, Any]],
+) -> list[dict]:
+    validate_aggregate_pipeline(pipeline, config.is_read_only)
+    safe_name = sanitize_table_name(collection)
+    cursor = conn.db[safe_name].aggregate(pipeline)
+    return await cursor.to_list(1000)

db_mcp_server-1.0.0/src/db_mcp/tools/describe.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import aiomysql
+
+from db_mcp.connection import Connection
+from db_mcp.validation import sanitize_table_name
+
+
+async def describe_mysql(conn: Connection, table: str) -> list[dict]:
+    safe_name = sanitize_table_name(table)
+    async with conn.pool.acquire() as c:
+        async with c.cursor(aiomysql.DictCursor) as cur:
+            await cur.execute(f"DESCRIBE {safe_name}")
+            return await cur.fetchall()
+
+
+async def describe_mongodb(conn: Connection, collection: str) -> list[dict]:
+    safe_name = sanitize_table_name(collection)
+    cursor = conn.db[safe_name].aggregate([{"$collStats": {"storageStats": {}}}])
+    return await cursor.to_list(10)

db_mcp_server-1.0.0/src/db_mcp/tools/execute.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from db_mcp.config import Config
+from db_mcp.connection import Connection
+
+
+async def execute_mysql(conn: Connection, config: Config, sql: str) -> dict:
+    if config.is_read_only:
+        raise ValueError(
+            "This database is in READ-ONLY mode. "
+            "Write operations are not allowed."
+        )
+
+    async with conn.pool.acquire() as c:
+        async with c.cursor() as cur:
+            await cur.execute(sql)
+            return {
+                "affectedRows": cur.rowcount,
+                "insertId": cur.lastrowid or 0,
+            }

db_mcp_server-1.0.0/src/db_mcp/tools/list_collections.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from db_mcp.connection import Connection
+
+
+async def list_collections(conn: Connection) -> list[str]:
+    return await conn.db.list_collection_names()

db_mcp_server-1.0.0/src/db_mcp/tools/list_tables.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import aiomysql
+
+from db_mcp.connection import Connection
+
+
+async def list_tables(conn: Connection) -> list[dict]:
+    async with conn.pool.acquire() as c:
+        async with c.cursor(aiomysql.DictCursor) as cur:
+            await cur.execute("SHOW TABLES")
+            return await cur.fetchall()

db_mcp_server-1.0.0/src/db_mcp/tools/query.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+import aiomysql
+
+from db_mcp.config import Config
+from db_mcp.connection import Connection
+from db_mcp.validation import validate_read_only_query
+
+
+async def query_mysql(conn: Connection, config: Config, sql: str) -> list[dict]:
+    if config.is_read_only:
+        validate_read_only_query(sql)
+
+    async with conn.pool.acquire() as c:
+        async with c.cursor(aiomysql.DictCursor) as cur:
+            await cur.execute(sql)
+            rows = await cur.fetchall()
+    return rows
+
+
+async def query_mongodb(
+    conn: Connection,
+    collection: str,
+    filter_obj: dict[str, Any] | None = None,
+    limit: int = 100,
+) -> list[dict]:
+    if filter_obj is None:
+        filter_obj = {}
+    capped = min(limit, 1000)
+    results = await conn.db[collection].find(filter_obj).limit(capped).to_list(capped)
+    return results

db_mcp_server-1.0.0/src/db_mcp/tools/status.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from db_mcp.config import Config
+
+
+def get_status(config: Config) -> dict:
+    info: dict = {
+        "type": config.db_type,
+        "database": config.db_database,
+        "mode": config.db_mode,
+        "status": "connected",
+    }
+    if config.is_mysql:
+        info["host"] = f"{config.db_host}:{config.db_port}"
+        info["user"] = config.db_user
+    else:
+        info["url"] = config.db_url
+    return info

db_mcp_server-1.0.0/src/db_mcp/validation.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import re
+
+_READ_ONLY_PREFIXES = ("select", "show", "describe", "explain", "with")
+
+
+def validate_read_only_query(sql: str) -> None:
+    trimmed = sql.strip().lower()
+    if not any(trimmed.startswith(p) for p in _READ_ONLY_PREFIXES):
+        raise ValueError(
+            "Only SELECT, SHOW, DESCRIBE, EXPLAIN, WITH queries are allowed "
+            "on read-only databases."
+        )
+
+
+def sanitize_table_name(name: str) -> str:
+    sanitized = re.sub(r"[^a-zA-Z0-9_]", "", name)
+    if not sanitized:
+        raise ValueError(f"Invalid table/collection name: {name!r}")
+    return sanitized
+
+
+def validate_aggregate_pipeline(pipeline: list, read_only: bool) -> None:
+    if not read_only:
+        return
+    for stage in pipeline:
+        if not isinstance(stage, dict):
+            continue
+        for key in stage:
+            if key in ("$out", "$merge"):
+                raise ValueError(
+                    f"Aggregation pipelines with {key} are not allowed "
+                    "on read-only databases."
+                )

db_mcp_server-1.0.0/src/db_mcp_server.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: db-mcp-server
+Version: 1.0.0
+Summary: MCP server for MySQL and MongoDB databases — one instance per database, no Docker required
+Author: Ing. Luca Stucchi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/stucchi/db-mcp-server
+Project-URL: Repository, https://github.com/stucchi/db-mcp-server
+Project-URL: Issues, https://github.com/stucchi/db-mcp-server/issues
+Keywords: mcp,database,mysql,mongodb,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]
+Requires-Dist: aiomysql
+Requires-Dist: motor
+Dynamic: license-file
+
+# db-mcp-server
+
+MCP server for MySQL and MongoDB databases. One instance per database, no Docker required.
+
+## Installation
+
+```bash
+uvx db-mcp-server
+```
+
+## Configuration
+
+Configure via environment variables. Each instance connects to a single database.
+
+### MySQL
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DB_TYPE` | Yes | — | `mysql` |
+| `DB_DATABASE` | Yes | — | Database name |
+| `DB_PASSWORD` | Yes | — | Password |
+| `DB_HOST` | No | `localhost` | Host |
+| `DB_PORT` | No | `3306` | Port |
+| `DB_USER` | No | `root` | User |
+| `DB_MODE` | No | `read-only` | `read-only` or `read-write` |
+
+### MongoDB
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DB_TYPE` | Yes | — | `mongodb` |
+| `DB_DATABASE` | Yes | — | Database name |
+| `DB_URL` | Yes | — | Connection URL (`mongodb://...`) |
+| `DB_MODE` | No | `read-only` | `read-only` or `read-write` |
+
+## Usage in .mcp.json
+
+```json
+{
+  "mcpServers": {
+    "db-prod": {
+      "command": "uvx",
+      "args": ["db-mcp-server"],
+      "env": {
+        "DB_TYPE": "mysql",
+        "DB_MODE": "read-only",
+        "DB_HOST": "db.example.com",
+        "DB_PORT": "3306",
+        "DB_USER": "root",
+        "DB_PASSWORD": "secret",
+        "DB_DATABASE": "myapp"
+      }
+    }
+  }
+}
+```
+
+For multiple databases, add multiple instances:
+
+```json
+{
+  "mcpServers": {
+    "db-prod": {
+      "command": "uvx",
+      "args": ["db-mcp-server"],
+      "env": { "DB_TYPE": "mysql", "DB_DATABASE": "prod", "..." : "..." }
+    },
+    "db-staging": {
+      "command": "uvx",
+      "args": ["db-mcp-server"],
+      "env": { "DB_TYPE": "mongodb", "DB_DATABASE": "staging", "..." : "..." }
+    }
+  }
+}
+```
+
+## Tools
+
+### MySQL
+
+- **query** — Execute read-only SQL (SELECT, SHOW, DESCRIBE, EXPLAIN, WITH)
+- **execute** — Execute write SQL (INSERT, UPDATE, DELETE) — requires `DB_MODE=read-write`
+- **describe** — Describe table structure
+- **list_tables** — List all tables
+- **status** — Show connection info
+
+### MongoDB
+
+- **query** — Find documents in a collection
+- **describe** — Collection stats ($collStats)
+- **list_collections** — List all collections
+- **aggregate** — Execute aggregation pipelines ($out/$merge blocked on read-only)
+- **status** — Show connection info
+
+## License
+
+MIT

db_mcp_server-1.0.0/src/db_mcp_server.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+pyproject.toml
+src/db_mcp/__init__.py
+src/db_mcp/__main__.py
+src/db_mcp/config.py
+src/db_mcp/connection.py
+src/db_mcp/server.py
+src/db_mcp/validation.py
+src/db_mcp/tools/__init__.py
+src/db_mcp/tools/aggregate.py
+src/db_mcp/tools/describe.py
+src/db_mcp/tools/execute.py
+src/db_mcp/tools/list_collections.py
+src/db_mcp/tools/list_tables.py
+src/db_mcp/tools/query.py
+src/db_mcp/tools/status.py
+src/db_mcp_server.egg-info/PKG-INFO
+src/db_mcp_server.egg-info/SOURCES.txt
+src/db_mcp_server.egg-info/dependency_links.txt
+src/db_mcp_server.egg-info/entry_points.txt
+src/db_mcp_server.egg-info/requires.txt
+src/db_mcp_server.egg-info/top_level.txt

db_mcp_server-1.0.0/src/db_mcp_server.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

db_mcp_server-1.0.0/src/db_mcp_server.egg-info/entry_points.txt

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

db_mcp_server-1.0.0/src/db_mcp_server.egg-info/requires.txt

@@ -0,0 +1,3 @@
+mcp[cli]
+aiomysql
+motor

db_mcp_server-1.0.0/src/db_mcp_server.egg-info/top_level.txt

@@ -0,0 +1 @@
+db_mcp