kampn/mariadb-mcp repository overview

⁠kampn/mariadb-mcp

MariaDB / MySQL MCP server (Model Context Protocol), packaged for the Docker MCP gateway and for direct use by MCP clients (Claude Code, Claude Desktop, Codex, …).

Speaks stdio by default. SSE on port 9001 stays available behind an argument.

• Tags: 0.2.6 (also 0.2.6-arm64 / 0.2.6-x86 single-arch builds)
• Architectures: linux/amd64, linux/arm64
• Base: python:3.11-slim
• License: MIT — third-party software vendored from MariaDB/mcp⁠ v0.2.6, repackaged. src/ is unmodified upstream code.

⁠Quick start

docker run --rm -i \
  -e DB_HOST=db.example.net \
  -e DB_PORT=3306 \
  -e DB_USER=myuser \
  -e DB_PASSWORD=mypassword \
  -e DB_NAME=mydb \
  kampn/mariadb-mcp:0.2.6

-i is required: the server talks MCP over stdin/stdout. Nothing is printed on stdout except JSON-RPC; logs go to stderr and to a file.

DB_USER and DB_PASSWORD are mandatory. The server raises ConnectionError at startup without them, before any tool is registered.

Writes are refused by default. MCP_READ_ONLY defaults to true, and execute_sql then raises PermissionError on any write. Set -e MCP_READ_ONLY=false if the client must write.

⁠Use as an MCP server

⁠Claude Code / Claude Desktop

{
  "mcpServers": {
    "mariadb": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DB_HOST=db.example.net",
        "-e", "DB_PORT=3306",
        "-e", "DB_USER=myuser",
        "-e", "DB_PASSWORD=mypassword",
        "-e", "DB_NAME=mydb",
        "-e", "MCP_READ_ONLY=true",
        "kampn/mariadb-mcp:0.2.6"
      ]
    }
  }
}

⁠Codex (~/.codex/config.toml)

[mcp_servers.mariadb]
command = "docker"
args = ["run", "-i", "--rm",
        "-e", "DB_HOST", "-e", "DB_PORT", "-e", "DB_USER",
        "-e", "DB_PASSWORD", "-e", "DB_NAME", "-e", "MCP_READ_ONLY",
        "kampn/mariadb-mcp:0.2.6"]

[mcp_servers.mariadb.env]
DB_HOST = "db.example.net"
DB_PORT = "3306"
DB_USER = "myuser"
DB_PASSWORD = "mypassword"
DB_NAME = "mydb"
MCP_READ_ONLY = "true"

⁠Docker MCP catalog entry

The image carries ENTRYPOINT ["python", "src/server.py"] with CMD ["--transport", "stdio"], so a catalog entry passes flags only:

registry:
  mariadb:
    title: MariaDB
    type: server
    image: kampn/mariadb-mcp:0.2.6
    command:
      - --transport
      - stdio
    secrets:
      - name: mariadb.password
        env: DB_PASSWORD
    env:
      - name: DB_HOST
        value: '{{mariadb.host}}'
      - name: DB_PORT
        value: '{{mariadb.port}}'
      - name: DB_USER
        value: '{{mariadb.user}}'
      - name: DB_NAME
        value: '{{mariadb.database}}'

⁠Tools

Six SQL tools, always registered:

Five more (create_vector_store, list_vector_stores, delete_vector_store, insert_docs_vector_store, search_vector_store) register only when EMBEDDING_PROVIDER is set.

⁠Environment variables

Configuration is environment-only. Everything is optional except DB_USER and DB_PASSWORD.

⁠Connection

⁠TLS

⁠Permissions

⁠Embeddings (optional)

⁠Logging

⁠SSE mode only

⁠SSE transport

docker run --rm -p 9001:9001 \
  -e DB_HOST=db.example.net -e DB_USER=myuser \
  -e DB_PASSWORD=mypassword -e DB_NAME=mydb \
  -e ALLOWED_HOSTS=myhost.example.net \
  kampn/mariadb-mcp:0.2.6 --transport sse --host 0.0.0.0

The MCP endpoint is /sse — e.g. http://<host>:9001/sse. /mcp returns 404 in SSE mode.

CLI arguments: --transport {stdio,sse,http} (default stdio), --host (default 127.0.0.1), --port (default 9001), --path (default /mcp, applies to the http transport only).

⁠Notes

• Breaking change, 2026-08-21. Tag 0.2.6 was republished with the stdio default. Before that date the same tag started in SSE with no argument. Run docker pull kampn/mariadb-mcp:0.2.6 on hosts that cached the old image; a stale one fails under the Docker MCP gateway with exec: "--transport": executable file not found in $PATH.
• A writable /app is required. The server opens /app/logs/mcp_server.log at import time. The image runs as root, so this works by default, but startup fails under --read-only or a non-root --user. Set LOG_FILE to a writable path, or mount a volume on /app/logs.
• No secret is baked into the image.
• Known upstream bug. Errors raised inside the embedding path surface as AttributeError: 'NoneType' object has no attribute 'GoogleAPIError', masking the real error, because google.api_core is not a declared dependency upstream. Affects the openai and gemini error paths only; happy paths are unaffected. Present identically in upstream v0.2.6 and deliberately not patched here, to keep src/ byte-identical to upstream.