mariadb/mariadb-shell-mcp-server

Verified Publisher

By MariaDB Corporation

•Updated about 17 hours ago

Multi-tenant MCP server for MariaDB, from MariaDB Shell: streamable HTTP, API keys, OAuth2, Keycloak

Image

580

Overview Tags

mariadb/mariadb-shell-mcp-server repository overview

⁠MariaDB Shell MCP Server

A multi-tenant MCP⁠ server that gives AI assistants and agents controlled access to MariaDB databases. It's built into MariaDB Shell⁠ and serves streamable HTTP. Every request carries an API key or an OAuth2 access token, and each user has their own database connections.

Platforms: linux/amd64, linux/arm64, based on debian:13-slim
Port: 8080, plain HTTP. Put a TLS-terminating reverse proxy in front of it.
Volume: /home/mcp holds the configuration, the users and the credential store with their API keys and connection passwords. Back it up, and don't share it.
Runs as: uid 10001

The image contains a MariaDB Shell release and nothing else: no MariaDB server. It serves only multi-tenant mode and the db tools. For an MCP client on your own machine, use the stdio transport of a local MariaDB Shell⁠ instead.

⁠Tags

Tag	Points at
`X.Y.Z`, for example `26.10.3`	that MariaDB Shell release
`X.Y`, for example `26.10`	the newest release of that line
`latest`	the newest release

The tags follow the MariaDB Shell releases, prereleases included.

⁠Quick Start

API keys only, with one user created on the first start:

docker run -d --name mcp -p 127.0.0.1:8080:8080 -v mcp-data:/home/mcp \
  -e [email protected] \
  -e MCP_ALLOWED_HOSTS=mcp.example.com \
  mariadb/mariadb-shell-mcp-server:26.10

# The user's API key, and a database connection for them
docker exec mcp mariadb-shell -- mcp setup [email protected]
docker exec -e ADA_DB_PASSWORD mcp mariadb-shell -- mcp setup [email protected] \
  --addConnection='mariadb://[email protected]:3306' --passwordEnv=ADA_DB_PASSWORD

Clients send the key as Authorization: Bearer <API key> to https://mcp.example.com/mcp. MCP_ALLOWED_HOSTS names the host that your reverse proxy passes on.

With Podman, use the fully qualified name docker.io/mariadb/mariadb-shell-mcp-server.

Choose one with MCP_OAUTH_MODE. API keys work in every mode.

Mode	Users sign in with
`none` (default)	API keys only
`builtin`	Their MariaDB account, on the server's own sign-in page. Users are created at their first sign-in.
`keycloak`	Keycloak. On its first start, the container prepares an existing realm.

⁠Main Environment Variables

Variable	Description
`MCP_OAUTH_MODE`	`none`, `builtin` or `keycloak`
`MCP_PUBLIC_URL`	The URL clients reach the endpoint at, for example `https://mcp.example.com/mcp`. Needed for `builtin` and `keycloak`.
`MCP_INITIAL_USER`	A user to create on the first start
`MCP_LOGIN_SERVERS`	`builtin`: the MariaDB servers users sign in to
`MCP_REQUIRED_ROLE`	`builtin`: the MariaDB role an account needs to sign in
`KEYCLOAK_URL`, `KEYCLOAK_REALM`, `KEYCLOAK_ADMIN_USER`, `KEYCLOAK_ADMIN_PASSWORD_FILE`	`keycloak`: the realm to prepare, and the administrator who prepares it
`MCP_TRUSTED_PROXIES`	The reverse proxy's addresses, whose `X-Forwarded-For` header the server trusts
`MCP_ALLOWED_HOSTS`	Additional `Host` header values to accept

The container applies the configuration on its first start and again only when a variable changes. Administer the server with docker exec mcp mariadb-shell -- mcp setup ….

⁠Documentation

Running in a Container⁠: complete Docker Compose and Podman setups behind a reverse proxy, with and without Keycloak
Image reference⁠: every environment variable, and the reverse proxy configuration
MariaDB Shell documentation⁠

⁠Source and License

Built from mariadb-corporation/mariadb-shell⁠ (docker/linux-debian13-mcp-server.Dockerfile). MariaDB Shell is licensed under the GPL, version 2. Report problems in the issue tracker⁠.

Tag summary

Recent tags

Content type

Image

Digest

sha256:9952ad0d3…

Size

126.6 MB

Last updated

about 17 hours ago

docker pull mariadb/mariadb-shell-mcp-server