Kirby MCP

CLI-first MCP server for Composer-based Kirby CMS projects. It lets an IDE or agent inspect your Kirby project (blueprints, templates, plugins, docs) and interact with a real Kirby runtime. It ships with a local knowledge base of Kirby concepts and tasks. For agent-specific install steps (Claude Code, Codex CLI) and Skill sync, see Client setup.

It can also run as a projectless global reference MCP (kirby-mcp --global) for always-on Kirby docs/KB research. Global reference mode is intentionally separate from project-local MCP servers and cannot inspect, render, update, or run commands in a Kirby project.

The server uses MCP SDK v0.8 dual-era dispatch: existing clients negotiate stateful sessions through initialize, while 2026-07-28 clients use stateless requests. MCP logging requests are not advertised—diagnostics are written to stderr instead. A valid W3C v00 traceparent supplied by a modern request, including the native HTTP header from browser clients, is included for correlation; tracestate and baggage are never logged.

[!WARNING] Prompt injection is a serious security threat, especially when used with documents retrieved from the internet. You might not see it happen when observing the conversation with the agent!

Quickstart

From your Kirby project root:

composer require bnomei/kirby-mcp --dev
vendor/bin/kirby-mcp install
vendor/bin/kirby-mcp

This quickstart is for a local stdio MCP server. If you want Kirby to serve a production HTTP /mcp route, install bnomei/kirby-mcp as a normal Composer dependency instead of --dev; see HTTP transport below.

Then configure your MCP client (Cursor/Claude Code/Codex CLI) using the examples in Client setup and copy the bundled Skills as described below.

See Client setup → Claude Code and Client setup → Codex CLI for per-agent install and Skill sync steps.

Global Reference Mode

Install once with Composer and run the global reference MCP anywhere:

composer global require bnomei/kirby-mcp
kirby-mcp --global

Use this mode for always-available Kirby research: bundled KB search, glossary, Panel field/section reference, hooks, extensions, update-schema guides, official docs search, and plugin directory search.

Global reference mode is projectless by design:

• It does not auto-detect or accept --project.
• It does not expose project/runtime tools such as kirby_roots, kirby_info, kirby_render_page, content updates, eval/query, runtime install, or IDE helper generation.
• If you need project context or mutations, add a separate project-local MCP server with vendor/bin/kirby-mcp.

Copy-paste request examples

Use these once your MCP client is connected to the server.

Planning & content

[!TIP] "Use the Kirby MCP to make a plan to..." is a reliable way to get your agent to use the tools and resources this MCP server provides. If you ask it to take action, it tends to edit files directly based on its training and skills.

Use the Kirby MCP to make a plan to... build a contact form page.

kirby_roots, kirby_blueprint_read, kirby_templates_index, kirby_snippets_index, kirby_controllers_index, kirby_render_page, kirby_dump_log_tail, kirby://config/{option}

Agent response example:

Here’s a Kirby MCP–driven plan for a new contact form page in this project: