MCP Mariadb Demo

mcp mariadb演示

MariaDB支持的Python MCP服务器的最小学习仓库。

此仓库保留了一个受支持的实现：

• 服务器： src/server.py
• 种子SQL： db/init/
• 非VS Code客户端的通用MCP客户端模板： mcp.json
• LLM MCP模板： anythingllm_mcp_servers.json
• VS代码工作区MCP配置： .vscode/mcp.json
• 配置指南： CONFIG.md

该演示展示了三个工具：

• ping_database
• list_tables
• run_readonly_query

重要提示：

• VS代码不使用根 mcp.json 文件。
• 任何LLM都不使用根 mcp.json 文件也。
• 根 anythingllm_mcp_servers.json 是复制到AnythingLLM的模板 plugins/ 存储目录。
• 根 mcp.json 只是其他期望顶级MCP客户端的通用模板 mcpServers 对象。
• VS代码使用 .vscode/mcp.json.

范围

此repo旨在教导：

• 小型MCP服务器的结构
• 如何从加载MariaDB连接设置 .env
• MCP客户端如何通过stdio连接
• 如何保持简单查询工具只读

它不试图涵盖打包、身份验证、矢量搜索或生产部署。

演示数据

种子SQL创建了一个小型IT/帮助台数据集，其中包含：

• users
• assets
• tickets
• knowledge_articles

快速启动

1. 创建虚拟环境并安装依赖项。

如果你正在使用 uv，从同步项目依赖关系 pyproject.toml:

uv sync

然后使用以下命令运行服务器：

uv run src/server.py

或

uv run src/server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp

如果你使用的是plain venv + pip，保持环境命名 .venv 如果你也想 uv 命令自动拾取它。一个单独的 venv/ 目录将不会被使用 uv run 除非你先激活它。

否则，标准 venv 流程仍然有效：

python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

1. 如果你需要Ubuntu或Debian上的本地MariaDB，请先安装。

对于本地服务器加上 mariadb CLI：

sudo apt update
sudo apt install -y mariadb-server mariadb-client
sudo systemctl enable --now mariadb

创建演示数据库和预期用户 .env.example:

sudo mariadb

CREATE DATABASE mcp_demo;
CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON mcp_demo.* TO 'mcp_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

如果您正在连接到现有的远程MariaDB， sudo apt install -y mariadb-client 够了。

1. 创建 .env 从模板中提取并将其指向MariaDB实例。

cp .env.example .env

1. 加载演示模式和数据。

mariadb -h  -P 
 -u  -p   -P 
 -u  -p   -P 
 -u  -p 

SHOW TABLES;
SELECT ticket_id, title, priority, status FROM tickets ORDER BY ticket_id;

示例查询

使用您的MCP客户端进行呼叫 run_readonly_query 与：

SELECT ticket_id, title, priority, status
FROM tickets
ORDER BY ticket_id;

SELECT u.full_name, a.asset_tag, a.model
FROM assets a
LEFT JOIN users u ON a.assigned_user_id = u.user_id
ORDER BY a.asset_tag;

备注

• src/server.py 加载根 .env 自动。
• src/server.py 支持 --transport stdio, --transport streamable-http，以及 --transport sse. --transport http 被接受为的别名 streamable-http.
• run_readonly_query 只允许以开头的SQL SELECT, SHOW, DESCRIBE，或 EXPLAIN.
• docker-compose.yml 如果你想要一个一次性本地MariaDB，它仍然可用，但它是可选的。
• mariadb-mcp/ 是一个scratch引用克隆，被git忽略；它不是活动演示的一部分。

有关客户端设置、VS Code聊天设置和故障排除，请参阅 CONFIG.md.