Maria MCP

MariaDB MCP Server

MCP server cho MariaDB/MySQL, chạy qua stdio bằng Python để agent tương tác trực tiếp với database của người dùng.

Thiết kế hiện tại bám theo các nguyên tắc sau:

• Chạy cục bộ trên máy người dùng.
• Agent phải xin credentials từ user và gọi configure_connection trong runtime.
• Không khóa vào một IDE hay agent cụ thể.

Flow hoạt động

1. MCP client chỉ cần khởi động process Python của server.
2. Khi cần truy cập database, agent phải hỏi user các thông tin kết nối như host, port, user, password, database.
3. Agent gọi tool configure_connection.
4. Agent gọi test_connection để xác nhận kết nối.
5. Các tool còn lại dùng cấu hình runtime đó cho tới khi process kết thúc hoặc được cấu hình lại.

Database credentials chỉ nằm trong memory của process hiện tại. Khi MCP server khởi động lại, agent phải cung cấp lại.

Yêu cầu

• Python 3.11+
• Một MariaDB/MySQL server mà máy của bạn truy cập được
• MCP client hỗ trợ giao tiếp qua stdio

Cài đặt

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

Chạy trực tiếp

Bạn có thể chạy thử server trong terminal mà không cần cấu hình database trước:

.venv/bin/python mariadb-mcp-server.py

Nếu muốn tăng log:

LOG_LEVEL=DEBUG .venv/bin/python mariadb-mcp-server.py

Cấu hình MCP client

Theo yêu cầu của project này, mcp_config chỉ nên chứa command và args.

Ví dụ:

{
  "mcpServers": {
    "mariadb": {
      "command": "/path/to/MariaMCP/.venv/bin/python",
      "args": [
        "/absolute/path/to/MariaMCP/mariadb-mcp-server.py"
      ]
    }
  }
}

Khuyến nghị dùng Python trong virtual environment thay vì python3 global để tránh lỗi thiếu package khi MCP client chạy bằng interpreter khác với terminal hiện tại của bạn.

Cách agent cung cấp credentials

Sau khi server đã được mount vào client, hãy đưa credentials cho agent trong cuộc hội thoại và yêu cầu agent cấu hình kết nối trước.

Ví dụ prompt:

Hãy cấu hình MariaDB MCP này bằng các thông tin sau rồi chạy test_connection:
host=127.0.0.1
port=3306
user=root
password=secret
database=app_db

Tool configure_connection nhận các field sau:

{
  "host": "127.0.0.1",
  "port": 3306,
  "user": "root",
  "password": "secret",
  "database": "app_db",
  "charset": "utf8mb4",
  "connect_timeout": 10
}

host và user là bắt buộc để mở kết nối. database là tùy chọn, vì bạn vẫn có thể truyền database trực tiếp cho từng tool như list_tables hoặc describe_table.

Antigravity

Ưu tiên Antigravity theo yêu cầu dự án. Cấu hình nên gọi trực tiếp Python process này qua stdio.

Ví dụ:

{
  "mcpServers": {
    "mariadb": {
      "command": "/path/to/MariaMCP/.venv/bin/python",
      "args": [
        "/path/to/MariaMCP/mariadb-mcp-server.py"
      ]
    }
  }
}

Nếu Antigravity báo calling "initialize": EOF, nguyên nhân thường là process Python thoát ngay khi khởi động. Cần kiểm tra:

• command có trỏ đúng tới Python interpreter mong muốn hay không
• đường dẫn tới mariadb-mcp-server.py có đúng hay không
• dependencies đã được cài bằng pip install -r requirements.txt hay chưa

Nếu agent báo kết nối chưa được cấu hình, đó là hành vi đúng của server mới. Hãy cung cấp credentials trong chat để agent gọi configure_connection.

Fix lỗi No module named 'mysql'

Nếu bạn thấy lỗi:

Traceback (most recent call last):
  ...
ModuleNotFoundError: No module named 'mysql'

thì nghĩa là MCP client đang khởi động bằng một Python chưa cài dependency từ requirements.txt.

Cách fix an toàn:

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

Sau đó cấu hình MCP client dùng đúng interpreter trong .venv.

Tools được expose

Lưu ý vận hành

• Đây là MCP server chạy qua stdio, không phải web service chạy nền lâu dài.
• Server chạy với quyền đúng bằng credentials mà agent đã cung cấp.
• Nếu agent có thể dùng execute_command, agent có thể thay đổi dữ liệu thật.
• Nên tạo riêng một user MariaDB với phạm vi quyền phù hợp thay vì dùng tài khoản admin cho production.