biz-db-mcp
Based on the provided schema, you can inspect configured databases and run bounded SQL with optional guarded DML and Parquet export (this schema differs from README v0.3: no instituteid, imports, list_tables, explain, or embedded-resource export).
list_databases: list configured database IDs without exposing DSNs or credentials.describe_table: return column metadata for a table in a configured database.query: run a bounded read-only SELECT with optional limit, params, and database.execute: execute one guarded DML statement when writes are explicitly enabled.export: stream a SELECT to Parquet and register it as a Sandbox Dataset, with destination session/identity taken from process-level environment variables.
Provides database operations for MySQL, including listing databases, describing tables, running read-only queries, executing protected single-statement DML writes, and exporting query results to Parquet for Sandbox Dataset uploads.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@biz-db-mcp show me the schema for the orders table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
biz-db-mcp
面向 UPRC 智能体平台的 MySQL MCP Server:按调用者机构隔离的只读查询、经 MCP 返回文件的导出,以及白名单内的产物导入。
v0.3 平台接入:Streamable HTTP + Bearer、宿主参数
instituteid、表替换式行级隔离、DBPM 原生 TCP 取密、config.yaml配置、导出改为 embedded resource、新增import_rows。迁移说明见文末。
设计边界
机构隔离:所有工具都有顶层必填字符串参数
instituteid,由平台按登录用户注入(模型看不到、改不了)。服务端按平台同一规则归一(0800001000→00001000),未知机构直接拒绝。行级过滤:模型写的 SELECT 用 sqlglot 解析,每个基表引用替换为
(SELECT * FROM 表 WHERE 机构列 IN (...)) AS 别名,对 JOIN、OR、外连接、聚合、子查询、UNION、CTE 同样成立。非公共表必须有机构列(isolation.column_candidates中第一个存在的列)或显式配置,否则视为不存在。SQL 准入:只允许单条 SELECT(含 WITH / UNION);含任何注释、锁定读、
INTO、变量、未知/危险函数、系统库的语句一律拒绝。只读:读连接使用最小权限读账号并设置
SESSION TRANSACTION READ ONLY;行数、序列化字节、执行时间都有上限,截断会标明原因。导出:生成 Parquet/CSV/JSONL 后以 MCP embedded resource(base64)返回,平台写入会话工作区。本服务不调用 Sandbox、不持有 Sandbox 凭据。超限整体失败,不截断。
导入:
import_rows默认关闭;只能写运维白名单内的表与列,机构列由服务端写入,单事务、持久幂等账本防重复写入。通用 DML:
execute/execute_many仅供本地 stdio 开发,HTTP 部署下拒绝启动。审计:stderr 输出 JSON 行,只含工具、机构码、库/表、SQL 摘要与长度、状态、错误码和耗时;不含 SQL 原文、参数、凭据、文件内容或结果数据。
Related MCP server: MySQL ReadOnly MCP Server
目录结构
biz_db_mcp/
config.py # config.yaml 加载与严格校验
institution.py # 机构号校验与归一
policy.py # 机构范围、表策略
sql_guard.py # SELECT 准入与表替换改写(另含开发用 DML 守卫)
db.py # 连接、元数据、隔离查询、导出流
credentials.py # 启动时一次性取齐数据库口令
dbpm.py # DBPM 原生 TCP 协议客户端
export.py # 固定 schema 的流式文件生成
mcp_files.py # 文件 → embedded resource
import_rows.py # 产物导入:校验、类型检查、事务写入
import_ledger.py # 幂等账本
limits.py # 并发槽与机构速率
transport.py # HTTP Bearer 鉴权与请求体上限
errors.py # 稳定错误码
audit.py # 结构化审计日志
server.py # MCP 工具与启动入口
migrations/ # DBA 执行的账本 DDL 与授权模板
tests/配置
全部可信配置放在一个 YAML 文件里,启动时加载一次,修改后重启生效。查找顺序:--config 参数 → $BIZDB_CONFIG → 当前目录 config.yaml。复制 config.example.yaml 为 config.yaml(已被 git 忽略)后修改。未知键会直接报错,避免拼写错误被悄悄忽略。
文件里不放秘密:
秘密 | 来源 |
MCP Bearer token |
|
数据库口令 | DBPM( |
本地开发口令 | 仅 stdio 且 DBPM 关闭时, |
DSN 中带口令会被拒绝。主要配置块:
块 | 作用 |
|
|
| query / export / import 的行数、字节、时间上限; |
| 两个 |
| 连接目录:无口令 DSN、DBPM 条目名、 |
| 归一机构码 → |
|
|
| 总开关与白名单表: |
| 仅本地 stdio 的通用 DML 开关 |
|
|
|
|
文件中的相对路径都相对配置文件所在目录解析。大小类配置可写整数字节或带单位,如 64KiB、20MiB、1G(按 1024 换算,MB 与 MiB 相同)。
存储占用
位置 | 内容 | 上限 |
| 审计 JSON 行 |
|
| 服务/SDK 日志 | 同上,示例 40 MiB;不配置路径则只写 stderr |
| 导出文件生成到返回之间的暂存,返回后立即删除 | 同时导出数( |
进程内存 | 导出 base64(约 1.33 × 文件)、导入解码字节与解析后的行、查询结果 | 导出约 27 MiB + JSON;导入 10 MiB 文件及最多 5 万行;查询 1 MiB |
MySQL 账本表 | 每次成功导入一行(约 300 B) | 不自动清理;服务账号无 DELETE 权限,按需由 DBA 定期清理很久以前的记录(清理后同一文件可再次导入) |
服务本身不写其他文件:DBPM 口令只在内存,MCP 无状态模式不存会话,速率桶按已配置的机构数有界。
工具
工具 | 说明 |
| 本机构可读的库 |
| 本机构可读的表/视图, |
| 列元数据 |
| 隔离后的只读 SELECT; |
| 隔离后 SELECT 的执行计划 |
| 结果文件以 embedded resource 返回;超限报 |
|
|
| 仅本地 stdio 且 |
错误统一为 isError 结果,文本以稳定错误码开头,如 FORBIDDEN_INSTITUTION、RESOURCE_NOT_ACCESSIBLE、SQL_REJECTED、TABLE_NOT_IMPORTABLE、CONTENT_DIGEST_MISMATCH、TOO_LARGE、RATE_LIMITED、BUSY、DEADLINE_EXCEEDED、IMPORT_OUTCOME_UNKNOWN。跨机构拒绝与“不存在”返回同一错误。
部署
安装
需要 Python 3.11 及以上。不依赖 uv,用标准 pip 即可:
python3 -m venv .venv
source .venv/bin/activate
# 生产:按锁定版本安装(与 uv.lock 一致)
python3 -m pip install -r requirements.txt
python3 -m pip install . --no-deps
# 开发:锁定版本 + pytest,项目以可编辑模式安装
python3 -m pip install -r requirements-dev.txt
python3 -m pip install -e . --no-deps也可以直接 python3 -m pip install -e '.[dev]',但这只按 pyproject.toml 的版本范围解析,装出的版本可能比锁文件新。
requirements*.txt 由 uv.lock 导出。修改依赖后需用文件头中的 uv export 命令重新生成,保持两者一致。
启动
python3 -m pytest
export BIZDB_MCP_TOKEN=... # 只有平台持有
biz-db-mcp --config /etc/biz-db-mcp/config.yaml --transport streamable-http --host 0.0.0.0 --port 8080端点为 http://<host>:<port>/mcp,无状态模式,便于多副本。容器以非 root 用户运行,经内网或 TLS 反向代理暴露。反向代理/网关的请求体上限至少为 server.max_request_bytes,响应上限需容纳 20 MiB 文件的 base64(约 27 MiB)加 JSON。服务端端到端期限(默认 150 秒)须低于平台 timeoutMs(示例 180 秒)。
平台清单示例:
{
"id": "bizdb",
"url": "https://bizdb-mcp.internal.example/mcp",
"authTokenRef": "BIZDB_MCP_TOKEN",
"timeoutMs": 180000,
"hostArguments": {"instituteid": {"description": "调用者机构号", "source": "user.instituteId"}},
"artifactArguments": {
"file_base64": {
"description": "已提交的待导入数据产物",
"modelArgument": "artifact_id",
"filenameArgument": "filename",
"sha256Argument": "content_sha256",
"maxBytes": 10485760,
"mimeTypes": ["text/csv", "application/x-ndjson", "application/vnd.apache.parquet"]
}
},
"fileResults": {"maxBytes": 20971520}
}平台清单的 maxBytes 是平台格式,只能写整数字节:10 MiB = 10485760,20 MiB = 20971520。
启用导入前:DBA 执行 migrations/001_import_ledger.sql,按其中模板给独立导入账号授权;核对目标表唯一约束含机构列。启动时会检查账本表,缺失则拒绝启动。
本地开发(stdio,DBPM 关闭):
server: {transport: stdio}
dbpm: {enabled: false}
databases:
primary: {dsn: "mysql://dev@127.0.0.1:3306/app", password_env: BIZDB_DEV_PASSWORD}
institutions:
"00002000": {scope: self}迁移说明(v0.2 → v0.3)
配置从环境变量改为
config.yaml。BIZDB_MYSQL_DSN、BIZDB_DATABASES_JSON、BIZDB_DBPM_*、BIZDB_SANDBOX_*、BIZDB_SESSION_ID/ORG_ID/USER_ID/CONVERSATION_ID等旧变量仍被设置时拒绝启动,并列出变量名。所有工具新增必填
instituteid;平台清单需同步配置hostArguments。export不再上传 Sandbox,也不再返回dataset_id;改为返回文本摘要 + embedded resource。query返回{rows, row_count, truncated, truncated_reason, ...};dry_run不再回显 SQL 与参数。DBPM 从外部桥接命令改为原生 TCP 协议;
BIZDB_DBPM_COMMAND/APP_NAME/APP_KEY/APP_IP不再使用。execute/execute_many只在本地 stdio 开发可用。
Available Tools
5 toolsdescribe_tableB
Return column metadata for a table in one configured database.
Inputs: table (required), database. Returns: result
executeC
Execute one guarded DML statement when writes are explicitly enabled.
Inputs: sql (required), params, database. Returns: object
exportA
Stream a SELECT to Parquet and register it as a Sandbox Dataset.
The destination session and acting identity come from process-level environment variables, never from model-supplied tool arguments.
Inputs: sql (required), dataset_name (required), params, database. Returns: object
list_databasesA
List configured database ids without exposing DSNs or credentials.
Inputs: no named parameters. Returns: result
queryA
Run a bounded read-only SELECT. Use export for bulk pulls.
Inputs: sql (required), limit, params, database. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clear, distinct purpose: listing databases, describing table metadata, running bounded reads, executing guarded writes, and exporting bulk data. Query and export both run SELECTs, but the descriptions clearly differentiate interactive reads from bulk dataset creation.
Naming is mixed: list_databases and describe_table follow a verb_noun pattern with underscores, while query, execute, and export are single verbs with no underscore. The convention is not consistent across the set, though all names are simple and readable.
Five tools is well-scoped for a database MCP server, covering exploration, schema inspection, querying, writing, and bulk export. Each tool earns its place without redundancy or omission.
The surface covers the core database lifecycle: list databases, describe tables, query, write, and export. A minor gap is the lack of a list_tables tool, but agents can work around it by querying information_schema or using describe_table directly.
Maintenance
Related MCP Connectors
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Guard AI agents' PostgreSQL/MySQL access via MCP: SQL audit, auth, masking, write approval
PostgreSQL, MySQL, OpenAPI/Swagger, and shared Agent Memory with scoped access.
Amazon Ads, Seller Central, Vendor Central and AMC data for AI agents. Read-only by default.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables direct interaction with MySQL databases through SQL queries, table exploration, and schema inspection with support for prepared statements and connection pooling.-
- AlicenseAqualityDmaintenanceEnables AI assistants to safely query MySQL databases with read-only access, featuring SQL injection protection, connection pooling, and automatic query limits for secure database exploration.4124 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to interact with MySQL databases through secure query execution, schema discovery, and multi-database support with configurable read/write permissions and built-in SQL injection protection.82 npmMIT
- AlicenseAqualityDmaintenanceEnables AI agents to safely interact with MySQL/MariaDB databases, supporting read-only queries by default with optional write operations and access control.8MIT