
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.
概览
只读的 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 文件配置。需要能访问数据库的网络。
安装
在 SourceWeft 中
- 打开 控制台中的 Sakila MCP,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
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).
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
LIMITis 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=JSONshapes. - 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:
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 ONLYmax_execution_time=statement_timeout_ms,lock_wait_timeout= 5 s- connection attributes
program_name=sakila-mcpandsakila_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, theSET_VARhint,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 aLIMIT.
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:
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.
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.
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:
Claude Desktop (claude_desktop_config.json):
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:
It reads the same mcpServers format as Claude Desktop. Save this as, say,
~/.config/sakila-mcp.ollmcp.json:
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:
/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
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:
.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:
来源:README.md,提交 a0439a4
工具
0版本历史
1- v0.1.2最新Nov 19, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分