mcp-sequel 0.1.1__py3-none-any.whl

mcp_sequel/adapters/__init__.py

@@ -0,0 +1,8 @@
+from mcp_sequel.adapters.mysql import MySQLAdapter
+from mcp_sequel.adapters.sqlite import SQLiteAdapter
+
+ADAPTERS: dict[str, type] = {
+    "mysql": MySQLAdapter,
+    "mariadb": MySQLAdapter,
+    "sqlite": SQLiteAdapter,
+}

mcp_sequel/adapters/base.py

@@ -0,0 +1,54 @@
+import datetime
+import decimal
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+def _serialize(value: Any) -> Any:
+    if isinstance(value, (datetime.date, datetime.datetime, datetime.timedelta)):
+        return str(value)
+    if isinstance(value, decimal.Decimal):
+        return str(value)
+    if isinstance(value, bytes):
+        return value.hex()
+    return value
+
+
+class ReadonlyViolationError(Exception):
+    pass
+
+
+@dataclass
+class QueryResult:
+    columns: list[str]
+    rows: list[list]
+    row_count: int
+    limit_applied: int | None
+
+
+class BaseAdapter(ABC):
+    ALLOWED_STATEMENTS: frozenset[str] = frozenset()
+    sqlglot_dialect: str = ""
+
+    def __init__(self, config: Any) -> None:
+        self.config = config
+
+    def guard_readonly(self, sql: str) -> None:
+        # No-op by default. Two strategies exist:
+        # - Connection-level enforcement (SQLite: file URI with mode=ro) — leave as no-op
+        # - Statement-level enforcement (MySQL: parse SQL, reject non-SELECT) — override this method
+        pass
+
+    @abstractmethod
+    def connect(self) -> Any: ...
+
+    @abstractmethod
+    def ping(self, conn: Any) -> bool: ...
+
+    @abstractmethod
+    def execute(self, conn: Any, sql: str, database: str | None) -> QueryResult: ...
+
+    @abstractmethod
+    def close(self, conn: Any) -> None: ...
+

mcp_sequel/adapters/mysql.py

@@ -0,0 +1,85 @@
+from typing import Any
+
+import mysql.connector
+import sqlglot
+
+from mcp_sequel.adapters.base import (
+    BaseAdapter,
+    QueryResult,
+    ReadonlyViolationError,
+    _serialize,
+)
+from mcp_sequel.tunnel import close_tunnel, open_tunnel
+
+
+class MySQLAdapter(BaseAdapter):
+    ALLOWED_STATEMENTS = frozenset({"SELECT", "SHOW", "DESCRIBE", "EXPLAIN", "USE"})
+
+    def __init__(self, config: Any) -> None:
+        super().__init__(config)
+        self.sqlglot_dialect = config.type  # "mysql" or "mariadb"
+        self._tunnel: Any = None
+
+    def guard_readonly(self, sql: str) -> None:
+        stmts = sqlglot.parse(sql, dialect=self.sqlglot_dialect)
+        if not stmts:
+            raise ReadonlyViolationError("could not parse SQL")
+        for stmt in stmts:
+            stmt_type = type(stmt).__name__.upper()
+            if stmt_type not in self.ALLOWED_STATEMENTS:
+                raise ReadonlyViolationError(
+                    f"{stmt_type} statement is not allowed in readonly mode"
+                )
+
+    def connect(self) -> Any:
+        if self.config.ssh_tunnel:
+            self._tunnel = open_tunnel(
+                self.config.ssh_tunnel,
+                self.config.host,
+                self.config.port,
+            )
+            host = "127.0.0.1"
+            port = self._tunnel.local_bind_port
+        else:
+            self._tunnel = None
+            host = self.config.host
+            port = self.config.port
+
+        return mysql.connector.connect(
+            host=host,
+            port=port,
+            user=self.config.user,
+            password=self.config.password,
+            database=self.config.database or None,
+            autocommit=True,
+        )
+
+    def ping(self, conn: Any) -> bool:
+        conn.ping(reconnect=True)
+        return True
+
+    def execute(self, conn: Any, sql: str, database: str | None) -> QueryResult:
+        cursor = conn.cursor()
+        try:
+            if database is not None:
+                cursor.execute(f"USE `{database}`")
+            cursor.execute(sql)
+            columns = (
+                [desc[0] for desc in cursor.description] if cursor.description else []
+            )
+            raw_rows = cursor.fetchall() or []
+            rows = [[_serialize(v) for v in row] for row in raw_rows]
+            return QueryResult(
+                columns=columns,
+                rows=rows,
+                row_count=len(rows),
+                limit_applied=None,
+            )
+        finally:
+            cursor.close()
+
+    def close(self, conn: Any) -> None:
+        conn.close()
+        if self._tunnel is not None:
+            close_tunnel(self._tunnel)
+            self._tunnel = None

mcp_sequel/adapters/sqlite.py

@@ -0,0 +1,36 @@
+import sqlite3
+from typing import Any
+
+from mcp_sequel.adapters.base import BaseAdapter, QueryResult, _serialize
+
+
+class SQLiteAdapter(BaseAdapter):
+    sqlglot_dialect = "sqlite"
+
+    def connect(self) -> sqlite3.Connection:
+        path = self.config.path
+        if self.config.readonly:
+            uri = f"file:{path}?mode=ro"
+            return sqlite3.connect(uri, uri=True)
+        return sqlite3.connect(path)
+
+    def ping(self, conn: sqlite3.Connection) -> bool:
+        conn.execute("SELECT 1")
+        return True
+
+    def execute(
+        self, conn: sqlite3.Connection, sql: str, database: str | None
+    ) -> QueryResult:
+        cursor = conn.execute(sql)
+        columns = [desc[0] for desc in cursor.description] if cursor.description else []
+        raw_rows = cursor.fetchall() or []
+        rows = [[_serialize(v) for v in row] for row in raw_rows]
+        return QueryResult(
+            columns=columns,
+            rows=rows,
+            row_count=len(rows),
+            limit_applied=None,
+        )
+
+    def close(self, conn: sqlite3.Connection) -> None:
+        conn.close()

mcp_sequel/config.py

@@ -0,0 +1,99 @@
+from pathlib import Path
+from typing import Annotated, Literal, Union
+
+from pydantic import BaseModel, Field, ValidationError
+
+
+class BaseConnectionConfig(BaseModel):
+    @property
+    def location(self) -> str:
+        raise NotImplementedError
+
+
+class SSHTunnelConfig(BaseModel):
+    host: str
+    port: int = 22
+    user: str
+    key_file: str | None = None
+    password: str | None = None
+
+
+class MySQLConfig(BaseConnectionConfig):
+    type: Literal["mysql", "mariadb"]
+    host: str
+    port: int = 3306
+    database: str | None = None
+    user: str
+    password: str
+    readonly: bool = True
+    row_limit: int | None = 1000
+    description: str | None = None
+    ssh_tunnel: SSHTunnelConfig | None = None
+
+    @property
+    def location(self) -> str:
+        host = self.host if self.port == 3306 else f"{self.host}:{self.port}"
+        loc = f"{self.user}@{host}"
+        if self.database:
+            loc += f"/{self.database}"
+        if self.ssh_tunnel:
+            ssh = self.ssh_tunnel
+            ssh_host = ssh.host if ssh.port == 22 else f"{ssh.host}:{ssh.port}"
+            loc = f"{ssh.user}@{ssh_host} -> {loc}"
+        return loc
+
+
+class SQLiteConfig(BaseConnectionConfig):
+    type: Literal["sqlite"]
+    path: str
+    readonly: bool = True
+    row_limit: int | None = 1000
+    description: str | None = None
+
+    @property
+    def location(self) -> str:
+        return self.path
+
+
+ConnectionConfig = Annotated[
+    Union[MySQLConfig, SQLiteConfig],
+    Field(discriminator="type"),
+]
+
+
+def config_dir() -> Path:
+    return Path.home() / ".config" / "mcp-sequel"
+
+
+def load_one(name: str) -> "ConnectionConfig | None":
+    path = config_dir() / f"{name}.json"
+    if not path.exists():
+        return None
+    from pydantic import TypeAdapter
+
+    adapter = TypeAdapter(ConnectionConfig)
+    return adapter.validate_json(path.read_text())
+
+
+def load_all() -> list[tuple[str, ConnectionConfig]]:
+    """Return [(name, config), ...] for all valid .json files in the config dir."""
+    directory = config_dir()
+    if not directory.exists():
+        return []
+
+    results = []
+    for path in sorted(directory.glob("*.json")):
+        name = path.stem
+        try:
+            from pydantic import TypeAdapter
+
+            adapter = TypeAdapter(ConnectionConfig)
+            config = adapter.validate_json(path.read_text())
+            results.append((name, config))
+        except ValidationError as e:
+            # Skip invalid configs but don't crash the server
+            import sys
+
+            print(f"WARNING: skipping {path.name}: {e}", file=sys.stderr)
+
+    return results

mcp_sequel/pool.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+from mcp_sequel.adapters import ADAPTERS
+from mcp_sequel.adapters.base import BaseAdapter
+from mcp_sequel.config import ConnectionConfig, load_one
+
+_pool: dict[str, tuple[ConnectionConfig, BaseAdapter, Any]] = {}
+
+
+def get_connection(conn_name: str) -> tuple[ConnectionConfig, BaseAdapter, Any]:
+    if conn_name in _pool:
+        cfg, adapter, conn = _pool[conn_name]
+        adapter.ping(conn)
+        return cfg, adapter, conn
+
+    cfg = load_one(conn_name)
+    if cfg is None:
+        raise ValueError(f"Connection '{conn_name}' not found")
+
+    adapter_class = ADAPTERS[cfg.type]
+    adapter = adapter_class(cfg)
+    conn = adapter.connect()
+    _pool[conn_name] = (cfg, adapter, conn)
+    return cfg, adapter, conn
+
+
+def close_all() -> None:
+    for cfg, adapter, conn in _pool.values():
+        try:
+            adapter.close(conn)
+        except Exception:
+            pass
+    _pool.clear()

mcp_sequel/server.py

@@ -0,0 +1,87 @@
+import json
+
+import sqlglot
+from mcp.server.fastmcp import FastMCP
+
+from mcp_sequel.adapters.base import ReadonlyViolationError
+from mcp_sequel.config import load_all
+from mcp_sequel.pool import get_connection
+
+mcp = FastMCP("mcp-sequel", instructions="MySQL database query tool")
+
+
+def _is_select_without_limit(sql: str, dialect: str) -> bool:
+    stmts = sqlglot.parse(sql, dialect=dialect)
+    if not stmts or len(stmts) != 1:
+        return False
+    stmt = stmts[0]
+    return isinstance(stmt, sqlglot.exp.Select) and stmt.args.get("limit") is None
+
+
+@mcp.tool()
+def list_connections() -> str:
+    """List all configured database connections."""
+    try:
+        connections = load_all()
+    except Exception as e:
+        return f"ERROR: failed to load configs: {e}"
+
+    if not connections:
+        from mcp_sequel.config import config_dir
+
+        return f"No connections configured. Add .json files to: {config_dir()}"
+
+    blocks = []
+    for name, cfg in connections:
+        readonly = "yes" if cfg.readonly else "no"
+
+        header = f"{name} ({cfg.location}) [{cfg.type}], readonly: {readonly}"
+        if cfg.description:
+            blocks.append(f"{header}\n  {cfg.description}")
+        else:
+            blocks.append(header)
+
+    return "\n\n".join(blocks)
+
+
+@mcp.tool()
+def query(connection: str, sql: str, database: str | None = None) -> str:
+    """Execute a SQL query on a database connection. Returns JSON with columns, rows, row_count, limit_applied."""
+    try:
+        cfg, adapter, conn = get_connection(connection)
+
+        if cfg.readonly:
+            adapter.guard_readonly(sql)
+
+        actual_sql = sql
+        limit_applied = None
+        if cfg.row_limit is not None and _is_select_without_limit(
+            sql, adapter.sqlglot_dialect
+        ):
+            actual_sql = sql.rstrip().rstrip(";") + f" LIMIT {cfg.row_limit}"
+            limit_applied = cfg.row_limit
+
+        result = adapter.execute(conn, actual_sql, database)
+        result.limit_applied = limit_applied
+
+        return json.dumps(
+            {
+                "columns": result.columns,
+                "rows": result.rows,
+                "row_count": result.row_count,
+                "limit_applied": result.limit_applied,
+            },
+            ensure_ascii=False,
+        )
+    except ReadonlyViolationError as e:
+        return f"ERROR: readonly violation: {e}"
+    except Exception as e:
+        return f"ERROR: {e}"
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

mcp_sequel/tunnel.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from sshtunnel import SSHTunnelForwarder
+
+from mcp_sequel.config import SSHTunnelConfig
+
+
+def open_tunnel(
+    ssh_cfg: SSHTunnelConfig, remote_host: str, remote_port: int
+) -> SSHTunnelForwarder:
+    kwargs: dict = {
+        "ssh_username": ssh_cfg.user,
+        "remote_bind_address": (remote_host, remote_port),
+    }
+    if ssh_cfg.key_file:
+        kwargs["ssh_pkey"] = str(Path(ssh_cfg.key_file).expanduser())
+    if ssh_cfg.password:
+        kwargs["ssh_password"] = ssh_cfg.password
+
+    tunnel = SSHTunnelForwarder((ssh_cfg.host, ssh_cfg.port), **kwargs)
+    tunnel.start()
+    return tunnel
+
+
+def close_tunnel(tunnel: SSHTunnelForwarder) -> None:
+    tunnel.stop()

mcp_sequel-0.1.1.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: mcp-sequel
+Version: 0.1.1
+Summary: MCP server for Claude that connects to MySQL, MariaDB, and SQLite databases
+Project-URL: Homepage, https://github.com/eukos/mcp-sequel
+Author-email: Eugene Kosyakov <eukos@yandex.by>
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,llm,mariadb,mcp,mysql,sqlite
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: mysql-connector-python>=8.0
+Requires-Dist: paramiko<3.0,>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: sqlglot>=20.0
+Requires-Dist: sshtunnel>=0.4
+Description-Content-Type: text/markdown
+
+# mcp-sequel
+
+MCP server for Claude that connects to MySQL, MariaDB, and SQLite databases. Query your databases using natural language. Supports multiple named connections, SSH tunnels, readonly mode, and per-connection row limits.
+
+## Install & Registration
+
+_Tip: ask Claude to read this README and set up the server for you._
+
+**Option 1: uvx (recommended)** — no installation needed, always runs the latest version:
+
+```bash
+claude mcp add mcp-sequel uvx mcp-sequel
+```
+
+**Option 2: from cloned repository:**
+
+```bash
+git clone https://github.com/eukos/mcp-sequel
+claude mcp add mcp-sequel uv run --directory /path/to/mcp-sequel mcp-sequel
+```
+
+## Configuration
+
+_Tip: ask Claude to read this README and create a connection config for you._
+
+One file per connection in `~/.config/mcp-sequel/`. The filename (without `.json`) becomes the connection name.
+
+```bash
+~/.config/mcp-sequel/
+├── production.json
+├── staging.json
+└── local.json
+```
+
+Each file is one connection. Examples:
+
+**MySQL / MariaDB**
+
+```json
+{
+  "type": "mysql",
+  "host": "db.example.com",
+  "port": 3306,
+  "user": "analyst",
+  "password": "secret",
+  "database": "myapp",
+  "readonly": true,
+  "row_limit": 1000,
+  "description": "Production replica, analytics only"
+}
+```
+
+| Field         | Required | Default | Description                                            |
+|---------------|----------|---------|--------------------------------------------------------|
+| `type`        | yes      | —       | `"mysql"` or `"mariadb"`                               |
+| `host`        | yes      | —       | hostname or IP                                         |
+| `user`        | yes      | —       | database user                                          |
+| `password`    | yes      | —       | database password                                      |
+| `port`        | no       | `3306`  | TCP port                                               |
+| `database`    | no       | —       | default database; can be overridden per query          |
+| `readonly`    | no       | `true`  | if true, only SELECT/SHOW/DESCRIBE/EXPLAIN are allowed |
+| `row_limit`   | no       | `1000`  | max rows returned; `null` for no limit                 |
+| `description` | no       | —       | human-readable label shown in `list_connections`       |
+| `ssh_tunnel`  | no       | —       | SSH tunnel config (see below); routes the connection through a bastion host |
+
+**MySQL via SSH tunnel**
+
+Use `ssh_tunnel` when the database is only reachable through a bastion/jump host. `host` and `port` in the top-level config refer to the DB as seen **from the SSH server** (commonly `localhost`).
+
+With a key file (most common):
+
+```json
+{
+  "type": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "user": "reader",
+  "password": "secret",
+  "database": "myapp",
+  "ssh_tunnel": {
+    "host": "bastion.example.com",
+    "user": "ubuntu",
+    "key_file": "~/.ssh/id_rsa"
+  }
+}
+```
+
+With an SSH password:
+
+```json
+{
+  "type": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "user": "reader",
+  "password": "secret",
+  "ssh_tunnel": {
+    "host": "bastion.example.com",
+    "user": "ubuntu",
+    "password": "sshpass"
+  }
+}
+```
+
+| Field      | Required | Default | Description                             |
+|------------|----------|---------|-----------------------------------------|
+| `host`     | yes      | —       | SSH server hostname or IP               |
+| `user`     | yes      | —       | SSH username                            |
+| `key_file` | no\*     | —       | path to private key file (`~` expanded) |
+| `password` | no\*     | —       | SSH password (if not using key file)    |
+| `port`     | no       | `22`    | SSH server port                         |
+
+\* at least one of `key_file` or `password` should be provided.
+
+**SQLite**
+
+```json
+{
+  "type": "sqlite",
+  "path": "/data/analytics.db",
+  "readonly": true,
+  "row_limit": 1000,
+  "description": "Local analytics database"
+}
+```
+
+| Field         | Required | Default | Description                                                        |
+|---------------|----------|---------|--------------------------------------------------------------------|
+| `type`        | yes      | —       | `"sqlite"`                                                         |
+| `path`        | yes      | —       | absolute path to the `.db` file                                    |
+| `readonly`    | no       | `true`  | if true, opens connection with `?mode=ro` (OS-level enforcement)   |
+| `row_limit`   | no       | `1000`  | max rows returned; `null` for no limit                             |
+| `description` | no       | —       | human-readable label shown in `list_connections`                   |
+
+Set permissions to owner-only:
+
+```bash
+chmod 600 ~/.config/mcp-sequel/*.json
+```
+
+## Usage
+
+After registering, restart Claude to load the server. Then try:
+
+- "List available database connections"
+- "Show databases for staging"
+- "How many customers do we have on production?"
+- "Show me the schema of the orders table"
+- "Query local: SELECT * FROM users LIMIT 10"
+- "Query production: show me the top 10 users by order count"
+
+## License
+
+MIT

mcp_sequel-0.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+mcp_sequel/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_sequel/config.py,sha256=uWlcsqNvFUgWq2SANEA9aak3y6k4kQ9qGr-Esi3fbbg,2604
+mcp_sequel/pool.py,sha256=bJeZTjFAKoXrgCMVXhccQjtyiEmhgI-m9jonBl0-1Bs,924
+mcp_sequel/server.py,sha256=yh1fCpp1XrtWrdVkFSJPdmeNiSPzeXScIZ2u4n5QMEk,2524
+mcp_sequel/tunnel.py,sha256=9Os6Zw47U-AdDccyrJ1ymU387_Gw6RK43caQD_4SiuQ,701
+mcp_sequel/adapters/__init__.py,sha256=SSGY9kK_jKuIQK_38Ri8BXJ4F32z2sZhTlgm6ao2yyk,222
+mcp_sequel/adapters/base.py,sha256=mHiUiibLRUMco7s9d9rJrszci9PRPzZfizQk62FCtA8,1374
+mcp_sequel/adapters/mysql.py,sha256=vp4mj410CrwAjW0NRXzHI4QerUBag8vQiyMo4vB-uts,2670
+mcp_sequel/adapters/sqlite.py,sha256=p_HjrWrEIOCP3Tj664pbGY3zfjBeXpwlLlcXHBc3lHg,1103
+mcp_sequel-0.1.1.dist-info/METADATA,sha256=a5Be4q15G_NOtqBQFKI64SaYiVic3SQk_gF7mrZ47gM,5840
+mcp_sequel-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mcp_sequel-0.1.1.dist-info/entry_points.txt,sha256=XDHdQ_JNIsHKhLsl85F5WmuS3UEnHL2PXlhz6LjlWpc,54
+mcp_sequel-0.1.1.dist-info/licenses/LICENSE,sha256=tdNgBtlRWF1KbLtPlYVZuomItZsT1Xrbab__zrlJpbY,1072
+mcp_sequel-0.1.1.dist-info/RECORD,,

mcp_sequel-0.1.1.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_sequel-0.1.1.dist-info/entry_points.txt

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

mcp_sequel-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Kosyakov
+
+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.