AI导哈

数据库协议服务器

MariaDB MCP Server是一个强大的模型上下文协议服务器，使AI助手能够与MariaDB数据库交互，提供模式探索、查询执行和高级功能。

  • by akworob
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 akworob/mariadb_mcp_server

使用说明

MariaDB MCP 服务器

一个功能强大的模型上下文协议（MCP）服务器，使像Claude这样的AI助手能够与您的MariaDB数据库进行交互。该服务器提供全面的数据库访问功能，包括模式探索、查询执行以及高级特性。

特点/特性

  • 🔍（放大镜图标，通常表示搜索、查看细节或调查的意思） 模式探索浏览数据库、表和详细的模式信息
  • 📊 表格/数据图表 查询执行执行只读和写入查询（可配置）
  • 文件/文档 多种输出格式JSON用于程序化使用，Markdown用于人类可读性
  • 文件夹图标 分页支持高效处理大型结果集
  • 🔒（锁形符号，常用于表示安全、保密或锁定状态） 安全特性参数化查询，防止SQL注入，只读模式
  • 🏊 该表情符号在中文中通常被理解为“游泳”的意思，可以简单翻译为“游泳”。不过，具体翻译可能因语境和使用场合的不同而有所变化。 连接池高效的数据库连接管理
  • ⚡（闪电符号，常用于表示速度、活力或警告） 演出查询超时、结果大小限制和优化的响应格式

安装

先决条件

  1. Python 3.8及以上版本 安装在您的系统上
  2. MariaDB Connector/C （Python MariaDB 连接器所需）

安装 MariaDB Connector/C

在 macOS 上：

brew install mariadb-connector-c
export MARIADB_CONFIG=$(brew --prefix mariadb-connector-c)/bin/mariadb_config

在Ubuntu/Debian上：

sudo apt-get update
sudo apt-get install libmariadb-dev

在RHEL/CentOS/Fedora上：

sudo yum install mariadb-connector-c-devel

在Windows上： 从（指定来源）下载并安装 MariaDB Connector/C 下载

安装依赖项

pip install -r requirements.txt

或者单独安装各个包：

pip install mcp mariadb

配置

环境变量

使用这些环境变量配置服务器：

# Required - Database Connection
export MARIADB_HOST="localhost"           # Database server hostname
export MARIADB_PORT="3306"               # Database server port
export MARIADB_USER="your_username"      # Database username
export MARIADB_PASSWORD="your_password"  # Database password
export MARIADB_DATABASE=""               # Default database (optional)

# Optional - Security & Performance
export MARIADB_READ_ONLY="true"         # Set to "false" to allow write queries
export MARIADB_POOL_SIZE="5"            # Connection pool size (default: 5)

Claude 桌面配置

将此添加到您的Claude桌面配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mariadb": {
      "command": "python",
      "args": ["/path/to/mariadb_mcp_server.py"],
      "env": {
        "MARIADB_HOST": "localhost",
        "MARIADB_PORT": "3306",
        "MARIADB_USER": "your_username",
        "MARIADB_PASSWORD": "your_password",
        "MARIADB_DATABASE": "your_database",
        "MARIADB_READ_ONLY": "true"
      }
    }
  }
}

备选方案：使用uvx（推荐使用，便于更新）

如果你将服务器打包并发布到PyPI：

{
  "mcpServers": {
    "mariadb": {
      "command": "uvx",
      "args": ["mariadb-mcp-server"],
      "env": {
        "MARIADB_HOST": "localhost",
        "MARIADB_PORT": "3306",
        "MARIADB_USER": "your_username",
        "MARIADB_PASSWORD": "your_password",
        "MARIADB_DATABASE": "your_database"
      }
    }
  }
}

可用工具

服务器提供以下工具：

1. 列出数据库

列出 MariaDB 服务器上所有可访问的数据库。

在Claude中的示例用法：

  • “有哪些可用的数据库？”
  • “显示所有数据库”

2. 列出表（或“显示表列表”）

列出特定数据库中所有带有元数据的表。

参数：

  • database_name数据库的名称
  • response_format“json”或“markdown”（默认：“markdown”）

在Claude中的示例用法：

  • “销售数据库中有哪些表？”
  • “列出my_app数据库中的所有表”

3. 获取表结构（get_table_schema）

获取特定表的详细架构信息。

参数：

  • database_name数据库名称
  • table_name表名
  • include_indexes包含索引信息（默认：true）
  • include_foreign_keys包含外键关系（默认：true）
  • response_format“json”或“markdown”

在Claude中的使用示例：

  • “给我看一下用户表的架构”
  • “订单表有哪些列？”

4. 执行查询

对数据库执行SQL查询。

参数：

  • database_name查询的数据库
  • query要执行的SQL查询
  • parameters参数化查询的查询参数（可选）
  • limit返回的最大行数（默认：100，最大：1000）
  • offset分页时要跳过的行数（默认：0）
  • response_format“json”或“markdown”

在Claude中的示例用法：

  • “查找上个月注册的所有用户”
  • “给我看看销量最高的10款产品”
  • “将订单12345的状态更新为‘已发货’”

5. 获取数据库统计信息

获取数据库的统计信息和元数据。

参数：

  • database_name数据库的名称
  • response_format“json”或“markdown”

在Claude中的示例用法：

  • “分析数据库有多大？”
  • “给我展示生产数据库的统计数据”

安全特性

只读模式

默认情况下，服务器以只读模式运行，仅允许执行SELECT、SHOW、DESCRIBE和EXPLAIN查询。要启用写操作：

export MARIADB_READ_ONLY="false"

防止SQL注入

  • 服务器使用参数化查询
  • SQL 注释会被自动去除
  • 在执行之前进行查询验证

连接安全性

  • 具有自动重连功能的连接池
  • 可配置的超时时间
  • 通过环境变量安全处理凭据

使用示例

配置完成后，您可以通过Claude与您的MariaDB数据库进行交互：

示例1：探索数据库结构

You: "What databases do I have access to?"
Claude: [Uses list_databases tool]

You: "Show me the tables in the ecommerce database"
Claude: [Uses list_tables tool]

You: "What's the structure of the customers table?"
Claude: [Uses get_table_schema tool]

示例2：查询数据

You: "Find the top 5 customers by total purchase amount"
Claude: [Uses execute_query to run an aggregation query]

You: "Show me all orders from last month"
Claude: [Uses execute_query with date filtering]

示例3：数据分析

You: "Analyze the sales trends for Q4"
Claude: [Uses multiple tools to explore schema and run analytical queries]

You: "What's the average order value by product category?"
Claude: [Uses execute_query with GROUP BY and aggregation]

故障排除

常见问题

  1. 连接错误验证您的数据库凭据并确保MariaDB正在运行
  2. 未找到 MariaDB Connector/C确保您已安装连接器并设置了MARIADB_CONFIG
  3. 权限被拒绝检查您的数据库用户是否具有适当的权限
  4. 查询超时复杂查询可能会超时；请考虑优化查询或增加超时时间

调试模式

要启用详细日志记录：

# In the server file, change:
logging.basicConfig(level=logging.DEBUG)

性能优化

最佳实践

  1. 使用索引确保您的表为常见查询设置了适当的索引
  2. 限制结果对于大表，始终使用 LIMIT 子句
  3. 参数化查询使用参数代替字符串拼接
  4. 连接池根据您的工作负载调整 MARIADB_POOL_SIZE

响应大小管理

  • 如果结果超过25,000个字符，将自动截断
  • 对于大型结果集，使用分页（限制/偏移）
  • 选择JSON格式进行程序化处理，选择Markdown格式提高可读性

发展

测试服务器

# Test connection
python mariadb_mcp_server.py

# The server will wait for MCP commands on stdin
# Press Ctrl+C to exit

扩展服务器

要添加新工具，请遵循以下模式：

@mcp.tool(
    name="your_tool_name",
    annotations={
        "title": "Human Readable Title",
        "readOnlyHint": True,
        "destructiveHint": False,
        "idempotentHint": True,
        "openWorldHint": True
    }
)
async def your_tool_function(params: YourInputModel) -> str:
    """Tool documentation"""
    # Implementation
    pass

许可证

MIT 许可证 - 详情请参见 LICENSE 文件

支持

对于问题、疑问或贡献：

  1. 查看故障排除部分
  2. 检查环境变量配置
  3. 确保MariaDB Connector/C已正确安装
  4. 验证数据库权限

更新日志

版本1.0.0（当前）

  • 初始发布，包含核心功能
  • 模式探索工具
  • 带分页的查询执行
  • 多种输出格式
  • 安全功能和连接池

路线图

  • [ ] 支持复杂操作的事务处理
  • [ ] 查询历史和缓存
  • [ ] 高级查询构建器辅助
  • [ ] 性能分析工具
  • [ ] 备份和恢复工具
  • [ ] 向量搜索功能（MariaDB 11.7+）

功劳/学分/资历

使用MCP Python SDK（FastMCP）和MariaDB Connector/Python构建。

相关 MCP