MariaDB AI Plugins

First-class MariaDB support for AI coding agents. This repo packages a curated set of agent skills and wires up the native, high-performance mariadb-shell MCP server.

Installing a plugin gives you three things:

• Skills — MariaDB reference material the agent reads when it becomes relevant: how ALTER TABLE behaves in MariaDB, how vector indexes work, which connector to use from Python or Java, how to move an application over from MySQL. Skills work straight away and need no database.
• An MCP server — a live connection to a MariaDB server, so the agent can read your schema, run queries, analyse a slow query with EXPLAIN, or start a throwaway test instance. This needs a one-time setup, described below.
• mariadb-shell — MariaDB's command-line shell, a port of MySQL Shell, installed automatically the first time an agent starts the MCP server. The MCP server runs inside it as a plugin, using its ability to securely store all database credentials. You can also use it yourself as a SQL client — run mariadb-shell and type \help.

New to MCP? The Model Context Protocol is a standardized interface for AI agents to call tools — here, the tools that talk to MariaDB.

Works with Claude Code, Codex, OpenCode, Pi and Hermes Agent — see Installation.

Prefer a guided start? The DevHub has the same installation steps plus hands-on tutorials — building a schema and deploying it on a throwaway server, versioned migrations with MSM, REST endpoints, and migrating off MySQL. Its source is in docs/.

Installation

The MariaDB AI Plugins use the standard plugin system of the harness where available.

Note: On first start, the plugin is going to download and extract the required MariaDB Shell package, unless a suitable one is already installed. Depending on the network connection speed this might take a bit of time.

Claude Code

/plugin marketplace add mariadb/ai-plugins
/plugin install dev@mariadb

Then configure the MCP server — see Configure the MCP server below.

Codex

codex plugin marketplace add mariadb/ai-plugins
codex plugin add dev@mariadb

Codex's /plugins slash command browses and enables plugins interactively; it takes no arguments, so adding a marketplace is done with the CLI above. See codex/dev-plugin/README.md for details.

Then configure the MCP server — see Configure the MCP server below.

OpenCode

OpenCode has no central marketplace. Merge the mcp block from opencode/dev-plugin/opencode.json into your opencode.json, point MARIADB_DEV_PLUGIN at the plugin dir, and symlink its flat skills/ into an OpenCode skills directory. Full steps in opencode/dev-plugin/README.md.

Then configure the MCP server — see Configure the MCP server below.

Pi

Pi 1.0 or later installs the repo itself as a package (the pi field in the root package.json). Its extension registers the MCP server with Pi's built-in MCP support, so there is no separate setup step:

pi install git:github.com/mariadb/ai-plugins   # this repo (skills + extension + MCP server)
# …or from a local checkout, at the repo root: pi install .

Run /mcp in pi to see the mariadb server. Coming from an older Pi with pi-mcp-adapter? Remove the adapter first — it replaces the built-in MCP support. Full steps in pi/dev-plugin/README.md.

That registers the server with pi; configuring what it may access is a separate step — see Configure the MCP server below.

Hermes Agent

Hermes installs a plugin straight from its folder in this repo — each one is a portable Agent Plugins v1 package:

hermes plugins install mariadb/ai-plugins#hermes/dev-plugin --enable
hermes plugins install mariadb/ai-plugins#hermes/guard-plugin --enable

The second package, mariadb-guard, stops the agent from using the MariaDB command-line clients for what the MCP tools do (see below). It is a separate package because Hermes runs hooks only from a Python plugin.

Then start a new Hermes session; MCP servers connect at session start. --enable is needed because Hermes installs portable packages disabled. On native Windows the MCP server needs an entry in Hermes' config.yaml. Full steps in hermes/dev-plugin/README.md.

Then configure the MCP server — see Configure the MCP server below.

Configure the MCP server (all harnesses)

The skills work on their own. The MCP server, however, starts out allowed to reach nothing — installing a plugin wires it up, but does not tell it what it may touch. Run this once per machine:

mariadb-shell -- mcp setup     # or mcp.setup() from an interactive shell

The MCP server is built as a MariaDB Shell plugin in order to take advantage of its high-performance database connections, credential management, sandbox handling and advanced database schema management.

If mariadb-shell isn't on your PATH, use the copy the launcher installed — ~/.local/bin/mariadb-shell, or %LOCALAPPDATA%\Programs\mariadb-shell\bin\mariadb-shell.cmd on Windows. The installer only prints a PATH hint; it never edits your shell profile. That copy appears the first time a plugin starts the MCP server, so either let the agent run once first, or install the shell yourself before configuring it.

The setup configures the following items — see the MCP server documentation for the full reference:

• Connections: the database connection URIs the LLM will be allowed to connect to. Each password is prompted for, verified, and stored in the shell's secret store, separately from your regular MariaDB Shell connections. Give each one a dedicated MCP account with only the privileges it needs — read-only access to certain schemas, say — to keep the LLM from performing potentially harmful operations on the database.
• Allowed paths: choose the local directories the server may access (the current directory is suggested as the default, shown as a full path).
• Migration tooling (Linux and macOS only, and offered by the menu on later runs rather than by the first-run walkthrough): downloads the MySQL-to-MariaDB migration tooling and extracts it into ~/.local/share/mariadb-migrator/<version>. See Migration tooling.

Database access goes through the MCP server

Once the plugins are installed, the agent uses the MCP server's tools, not mariadb, mariadb-shell, mariadb-dump or another command-line client run from its shell, for anything those tools do. Such a client needs the password on its command line or in its environment, where it lands in the process list, in logs, and in the conversation the model provider sees. The MCP server reads each password from the secret store, so the agent never sees one. Configure the servers the agent may use with mariadb-shell -- mcp setup or its command-line options, and let it deploy sandboxes for local testing.

Two layers keep it that way:

• The MCP server's instructions, which a harness puts in the system prompt, and its tool descriptions say so, and ask the agent to deploy sandboxes with a random password.
• A guard blocks a shell command that uses mariadb or mysql to run SQL, mariadb-shell or mysqlsh in SQL mode or for an API call a tool wraps (-- util dump-schemas), or mariadb-dump piped into another client, and tells the model which tool to use instead. Everything the tools do not cover still runs, so the agent keeps the clients' other features. The guard is a PreToolUse hook in the Claude Code and Codex plugins, the Pi extension itself, an OpenCode plugin, and the separate mariadb-guard package for Hermes. Codex runs it only after you have trusted the plugin's hooks once in an interactive session.

To let the agent run the clients regardless, start it with MARIADB_PLUGIN_ALLOW_CLI=1 in its environment.

What you can ask for

With skills alone, no database connection needed:

Write a CREATE TABLE for a product catalogue, MariaDB style. What changes if I move this application from MySQL to MariaDB? How do I do semantic search in MariaDB? Show me how to connect to MariaDB from Node.js.

With the MCP server connected, against your real database:

What does the schema of my orders table look like? Why is this query slow? Run EXPLAIN on it. Which of my tables have no primary key? Deploy a test instance and try this migration on it first.

No database yet? The MCP server can deploy a throwaway MariaDB instance locally — no Docker, no container runtime, no administrator rights:

Deploy a MariaDB sandbox on port 3310. Spin up a test instance, apply this schema to it and show me the result. Try this migration on a sandbox before I run it for real. Stop and delete the sandbox, I'm done with it.

Instances live under ~/.mariadb-shell/sandboxes/<port>/ on macOS and Linux and under %USERPROFILE%\MariaDB\mariadb-shell\sandboxes\<port>\ on Windows.

Four things to know regarding sandbox instances:

• MariaDB Server does not need to be installed. The sandbox looks for a server on the PATH, then among the versions it has already downloaded, then in its published index — fetching, checksum-verifying and unpacking one if it has to. You can also ask for a version (server_version="11.8"), and sandbox.list_available_versions says what is on offer for your platform.
• A database connection to the sandbox is automatically registered with the MCP server.
• The sandbox is deployed without TLS, so command-line clients may need --skip-ssl.
• A root@'%' account is created and the sandbox listens on all interfaces, which is worth changing outside a trusted network.

The MCP server provides 40 tools in four groups:

Group	Tools	What they do
db.*	8	list connections and schemas, describe objects, run SQL
msm.*	12	MariaDB Schema Management — versioned schema projects, releases, deployments
sandbox.*	8	list deployable server versions; deploy, start, stop and delete local throwaway instances
util.*	12	dump, load, export, import and copy data between servers, as background tasks

Plugin variants

Each agent ships the plugin variants below — all built by the same scripts/sync-skills.sh:

Plugin	Skills	MCP server	Skills source
dev	full set — statements, functions, client tools, connectors, topical (+ all local additional-skills/: sql, rest, schema-management)	yes	mariadb-docs + additional-skills/
sql	SQL-focused subset — statements, functions, topical (+ local additional-skills/sql)	yes	mariadb-docs + additional-skills/sql/
contributor	skills for contributing to MariaDB tooling	no	mariadb-shell .claude/skills/

The folders are <agent>/{dev,sql,contributor}-plugin/ for each of claude/, codex/, opencode/ and hermes/; pi/ ships dev only for now. Skills are baseline MariaDB 11.8 LTS; the dev and sql plugins share the same auto-downloading mariadb-shell MCP server, while contributor is skills-only for now.

Pi differs from the other three in how it packages the same content: it has no marketplace file. A pi package is any directory with a package.json carrying a pi field, so the repo-root package.json is the manifest (its pi field points into pi/dev-plugin/) and the whole repo installs as one pi package. The package's extension registers the MCP server with Pi's built-in MCP support (Pi 1.0+). See pi/README.md.

Hermes Agent installs each plugin folder on its own as a portable Agent Plugins v1 package — a root plugin.json, skills/ and, for dev and sql, a root mcp.json — so it needs no marketplace file either. Its plugin names are mariadb-dev, mariadb-sql and mariadb-contributor.

Documentation site

docs/ holds the DevHub — a static Getting Started site served by GitHub Pages' built-in Jekyll from the /docs folder of main. It has no build step and no theme gem.

gem install jekyll jekyll-seo-tag jekyll-sitemap   # once
npm run docs                                       # → http://127.0.0.1:4000/ai-plugins/

See docs/README.md for how to publish it and add a tutorial. Note that its skill catalog is generated from the vendored manifests — re-run npm run docs:skills after scripts/sync-skills.sh.

Contributing

Working on the plugins rather than with them — how they are built, the repository layout, the skills sync and the test tiers — is covered in CONTRIBUTING.md.

License

Plugin code largely depends on the MariaDB Shell MCP plugin and is therefore licensed under GPL-2.0 — see LICENSE; each plugin ships an identical copy.

The bundled skills are vendored from several source repositories and retain their original licenses. The topical layer, for instance, carries its own LICENSE and VENDORED.md upstream in mariadb-corporation/mariadb-docs/agent-skills/topical. See additional-skills/README.md for the full list of sources and their licensing.