Sakila MCP

io.github.pantoniades由 GitHub 帳號 pantoniades 發布v0.1.2更新於 Nov 19, 2026

Read-only MySQL MCP server with a fail-closed SQL classifier and structured results.

已驗證STDIO僅桌面資料庫資料與分析

概覽

AI 產生的概覽

唯讀的 MySQL MCP 伺服器,讓助理檢視資料庫與資料表結構、執行單一 SELECT 查詢並讀取執行計畫,中間有失敗即拒絕的 SQL 分類器。

可以做什麼
  • 檢視伺服器資訊:MySQL 版本與發行線、運作時間、時區及關鍵全域變數
  • 列出可查詢的資料庫與資料表,標示系統結構並提供引擎、列數與大小估算
  • 描述資料表的欄位、索引、外鍵、引擎與定序
  • 執行單一唯讀語句,參數以佔位符綁定,回傳結構化的欄位與資料列
  • 以 JSON 或樹狀格式解釋查詢,並彙整全表掃描、檔案排序與暫存表
  • 讀取 capabilities 資源,了解版本與 EXPLAIN 格式支援情形
適用情境
適合讓助理探索不熟悉的 MySQL 結構、回答資料表之間關係的問題,或診斷查詢為何變慢,同時不授予寫入權限。
執行需求
以 uvx 執行的本機程序,需要 Python 3.12 以上與 uv。需要一個 MySQL 8.4 以上(8.0 盡力支援)的唯讀帳號。透過 SAKILA_MCP_HOST、SAKILA_MCP_PORT、SAKILA_MCP_USER(必填)、SAKILA_MCP_PASSWORD、SAKILA_MCP_DATABASE_ALLOWLIST 或 --config 指定的 TOML 檔設定。需要能連線到資料庫的網路。
安裝前請注意
資料庫允許清單只是名稱過濾,並非隔離邊界,真正的邊界是帳號的授權,應使用專用的唯讀帳號。information_schema、performance_schema 與 sys 永遠可讀,SHOW PROCESSLIST 或 PROCESS 權限會揭露其他工作階段的 SQL 與字面值。密碼保存在 SAKILA_MCP_PASSWORD 或設定檔中,檔案應設為 chmod 600 並排除於版本控制之外。唯讀模式無法關閉。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Sakila MCP,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

sakila-mcp

sakila-mcp is an MCP server that lets an LLM agent inspect and query any MySQL database, read-only, with a fail-closed SQL classifier between the agent and the server.

sakila-mcp is a general-purpose MySQL MCP server for any MySQL database. It is named after Sakila, the MySQL dolphin mascot, and is not specific to the Sakila sample database.

Independent open-source project. Not affiliated with, sponsored by or endorsed by Oracle. MySQL is a trademark of Oracle and/or its affiliates.

Status: v0.1 (0.1.1 is the first release on PyPI). What's described here works today. Expect the interface to change.

Quickstart

You need uv and a MySQL account that can only read (the grants are under Safety model).

sh
cat > ~/.config/sakila-mcp.toml <<'EOF'host = "db.example.internal"user = "sakila_mcp"password = "..."database_allowlist = ["app_db"]EOFchmod 600 ~/.config/sakila-mcp.toml
claude mcp add sakila -- uvx sakila-mcp --config ~/.config/sakila-mcp.toml

Then ask "what's in app_db and how do orders relate to customers?" or "why is this query slow?". Any MCP client that speaks stdio works; see Use it.

What makes it different

  • It fails closed. A statement the classifier can't parse is refused, and so is any function that isn't a known MySQL built-in.
  • It doesn't trust one lexer. Comments are re-scanned with MySQL's own rules, because a parser and the server can disagree about where a comment ends.
  • A refusal is a result, not an error: a code, a reason and a suggestion, so the agent can rephrase instead of giving up.
  • Everything is bounded without touching your SQL: rows, cell size and execution time are capped, and no LIMIT is ever added to a query.
  • The classifier isn't the only layer. Sessions are read-only transactions, re-initialised on every checkout, and the connection can't send more than one statement.
  • It knows MySQL's release lines (LTS, Innovation, calendar versions) and reads both EXPLAIN FORMAT=JSON shapes.
  • It says where it stops: the database allowlist is a name filter, and the real boundary is the account's grants.

What it does

Six tools, all read-only:

ToolReturns
server_infoMySQL version and release line (LTS / Innovation), uptime, session time zone, key globals (buffer pool, binlog format, GTID mode, read_only, sql_mode, charset), and the sakila-mcp version.
list_databasesDatabases you're allowed to query, system schemas flagged.
list_tablesTables and views in one database: engine, approximate rows, data and index size.
describe_tableColumns, indexes (key parts in order, uniqueness, cardinality), foreign keys, engine, row format, collation.
run_queryColumns and rows for one statement, capped at max_rows. Parameters via ? placeholders.
explain_queryEXPLAIN FORMAT=JSON plus a summary (full table scans, filesort, temporary tables, largest row estimate), or FORMAT=TREE text. Doesn't run the query.

Plus one resource, mysql://capabilities: version, release line, EXPLAIN JSON format version, and whether sys is visible.

Results are structured, not prose. DECIMAL comes back as a string so it stays exact, dates and times as ISO 8601, JSON parsed, binary as <binary N bytes>. Long cells are cut at max_cell_bytes with a marker saying how big they were.

When the server says no, the agent gets a result with refused: true, a reason and a suggestion, not an error, so it can rephrase. That includes SQL the classifier can't parse. Mistakes MySQL reports (unknown table or column, wrong parameter count) and infrastructure failures are tool errors.

Safety model

Every session, on every pool checkout:

  • SET SESSION TRANSACTION READ ONLY
  • max_execution_time = statement_timeout_ms, lock_wait_timeout = 5 s
  • connection attributes program_name=sakila-mcp and sakila_mcp_version, and every statement is tagged /* sakila-mcp tool=... */, so you can find it in the processlist and performance_schema

Every statement from run_query and explain_query goes through a SQL classifier (sqlglot plus token-level checks) before it reaches MySQL. It fails closed: if it can't parse it, it refuses it.

  • Allowed: one SELECT, WITH, TABLE, VALUES, DESCRIBE, EXPLAIN, or a SHOW from a fixed list.
  • Refused: everything else, more than one statement, /*! ... */ version comments, INTO (OUTFILE, DUMPFILE, variables), locking reads (FOR UPDATE, FOR SHARE), := assignment, the SET_VAR hint, EXPLAIN ANALYZE (it executes), functions that block, lock, wait or read files (SLEEP, BENCHMARK, GET_LOCK, LOAD_FILE, ...), and any function that isn't a known built-in (stored functions can write).
  • Parameters are bound by the server (PREPARE / EXECUTE ... USING), never spliced into the SQL.
  • Results stop at max_rows; the query is cut off, not rewritten with a LIMIT.

The database allowlist is a filter on names, not an isolation boundary. information_schema, performance_schema and sys are always readable, and SHOW PROCESSLIST, SHOW ENGINE INNODB STATUS and performance_schema statement history show other sessions' SQL, literal values included. The mysql schema is denied unless you list it.

The real boundary is the account's grants. Give sakila-mcp its own account with only what it needs:

sql
CREATE USER 'sakila_mcp'@'%' IDENTIFIED BY '...';GRANT SELECT, SHOW VIEW ON app_db.* TO 'sakila_mcp'@'%';-- Optional: SHOW PROCESSLIST / SHOW REPLICA STATUS. PROCESS exposes other sessions' SQL.GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'sakila_mcp'@'%';

The password never appears in tool results, logs or error text. There's a test for that.

Requirements

  • Python 3.12 or later and uv
  • MySQL 8.4 or later. CI runs the integration tests against 8.4, 9.7 and 26.10. 8.0 is tested best-effort: failures there don't block a release, and functions that exist only in 8.0 are refused as unknown.

Install

Nothing to install: uvx sakila-mcp downloads and runs the latest release. Pin a version with uvx [email protected], or install it with uv tool install sakila-mcp.

sh
uvx sakila-mcp --help

To run from a checkout instead, see Development.

Configure

Environment variables (SAKILA_MCP_*), a TOML file passed with --config, or both. Environment variables win over the file. Keep the password in the file, chmod 600 it, and keep it out of version control.

toml
# ~/.config/sakila-mcp.tomlhost = "db.example.internal"port = 3306user = "sakila_mcp"password = "..."database_allowlist = ["app_db"]   # empty = every non-system database
KeyEnv varDefault
hostSAKILA_MCP_HOST127.0.0.1
portSAKILA_MCP_PORT3306
userSAKILA_MCP_USER(required)
passwordSAKILA_MCP_PASSWORDempty
database_allowlistSAKILA_MCP_DATABASE_ALLOWLISTempty (all)comma-separated in the env var
max_rowsSAKILA_MCP_MAX_ROWS200rows returned per query
max_cell_bytesSAKILA_MCP_MAX_CELL_BYTES4096longer cells are truncated
statement_timeout_msSAKILA_MCP_STATEMENT_TIMEOUT_MS10000session max_execution_time
pool_sizeSAKILA_MCP_POOL_SIZE4
read_onlySAKILA_MCP_READ_ONLYtruefalse refuses to start; there is no write mode

The server connects to MySQL on the first tool call, not at startup. It starts and lists its tools even when MySQL is down; a wrong host or password shows up as a tool error on the first call (and in stderr), and the next call tries again.

Use it

Claude Code:

sh
claude mcp add sakila -- uvx sakila-mcp --config ~/.config/sakila-mcp.toml

Claude Desktop (claude_desktop_config.json):

json
{  "mcpServers": {    "sakila": {      "command": "uvx",      "args": ["sakila-mcp", "--config", "/home/you/.config/sakila-mcp.toml"]    }  }}

Ollama, with local models. Ollama runs the model but isn't an MCP client itself, so use ollmcp (mcp-client-for-ollama), a terminal client that connects Ollama models to MCP servers:

sh
uv tool install ollmcp

It reads the same mcpServers format as Claude Desktop. Save this as, say, ~/.config/sakila-mcp.ollmcp.json:

json
{  "mcpServers": {    "sakila": {      "command": "uvx",      "args": ["sakila-mcp", "--config", "/home/you/.config/sakila-mcp.toml"]    }  }}

and start it with a model that supports tool calling. ollama show <model> lists tools under Capabilities, and https://ollama.com/search?c=tools lists the models that have it:

sh
ollmcp -j ~/.config/sakila-mcp.ollmcp.json -m <model>

/tools inside ollmcp turns individual tools on and off. Model choice matters more here than with a hosted model: a model that is too small may call the wrong tool, invent arguments, or stop after one call. If that happens, try a larger one. That's a model problem, not a safety one. The server enforces the same rules whatever is calling it.

Then ask it things like "what's in app_db and how do orders relate to customers?" or "why is this query slow?".

Not in v0.1

Write mode, more than one server per process, HTTP transport, replication / InnoDB / lock diagnostics, Enterprise Edition features, EXPLAIN ANALYZE, stored functions.

Development

sh
git clone https://github.com/pantoniades/sakila-mcp.gitcd sakila-mcpuv syncuv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest

Integration tests need a MySQL server prepared once with tests/integration/setup.sh. Give it the address the server sees the tests connect from and a letters-and-digits password (extra arguments go to the mysql client), then point the tests at the server:

sh
SAKILA_MCP_TEST_CLIENT_HOST=127.0.0.1 SAKILA_MCP_TEST_PASSWORD=<password> \  tests/integration/setup.sh -u root -pecho 'SAKILA_MCP_TEST_DSN=mysql://sakila_mcp_test:<password>@<host>:3306/sakila_mcp_test' > .env.test

.env.test is gitignored. Without it the integration tests skip.

One test is opt-in: it drives Claude Code (claude -p) through every tool against the test server and checks that the client accepts each result. It needs the claude CLI, uses your account, and never runs in CI:

sh
uv run pytest -m llm

來源:README.md,提交 a0439a4

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.1.2最新Nov 19, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分