mcp-sequel 0.1.1__tar.gz

mcp_sequel-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  check-lock:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Verify uv.lock is up to date
+        run: uv lock --check
+
+  test:
+    needs: check-lock
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} pytest

mcp_sequel-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Check version changed
+        id: version
+        run: |
+          VERSION=$(grep '^version' pyproject.toml | cut -d'"' -f2)
+          PREV=$(git diff HEAD~1 pyproject.toml | grep '^\-version' | cut -d'"' -f2)
+          if [ -z "$PREV" ]; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+            echo "version=$VERSION" >> $GITHUB_OUTPUT
+          fi
+      - uses: astral-sh/setup-uv@v5
+        if: steps.version.outputs.changed == 'true'
+      - name: Build
+        if: steps.version.outputs.changed == 'true'
+        run: uv build
+      - name: Publish to PyPI
+        if: steps.version.outputs.changed == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Tag release
+        if: steps.version.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag "v${{ steps.version.outputs.version }}"
+          git push origin "v${{ steps.version.outputs.version }}"

mcp_sequel-0.1.1/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checkers
+.mypy_cache/
+.ruff_cache/
+
+# Tools
+.pdm-python
+.env
+.envrc
+
+# IDE
+.idea/
+.vscode/
+.qlty/

mcp_sequel-0.1.1/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.

mcp_sequel-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,154 @@
+# 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/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-0.1.1/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-0.1.1/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-0.1.1/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()