Kirby MCP Server - inspect blueprints/templates/plugins, interact with a real Kirby runtime, and use a bundled knowledge base

Resources Plugins
1

I am creating posts for my plugins to make it easier to find them using the forum search and not just the docs search.

plugin-image-kirby-mcp
plugin-image-kirby-mcp1024Ă—512 48.7 KB

Kirby MCP

Kirby MCP is a CLI-first MCP server for Composer-based Kirby projects that lets IDEs and agents inspect your project (blueprints / templates / snippets / controllers / models / plugins / routes), query a real Kirby runtime, and lean on a bundled Kirby knowledge base with an online docs fallback. It keeps risky actions guarded and installs lightweight runtime wrappers into your project for reliable runtime introspection.

Highlights:

  • Works with common MCP clients (Cursor, Claude Code, Codex CLI, …) and runs directly from your Kirby project
  • AI optimized local knowledge base with 182 docs speeds up Kirby lookups and reduces external dependency
  • Runtime-aware tools for inventory, rendering, content reads/updates, and debugging via mcp_dump()
  • Guardrails around write/eval and CLI commands, configurable via .kirby-mcp/mcp.json

Example

:information_source: “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 prompt 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:
  • Confirm requirements: fields (name/email/message), spam protection (honeypot + csrf()), success UX (inline vs redirect), and whether to store submissions.
  • Panel setup: reuse existing blueprint site/blueprints/pages/contact.yml; update site/blueprints/site.yml so the site “pages” section allows creating template contact.
  • Create the page: add content/4_contact/contact.txt (or create via Panel once allowed) and fill recipient, subject, success, text.
  • Frontend: add site/templates/contact.php + a snippet like site/snippets/contact-form.php (escape all echoed user input; include hidden CSRF field + honeypot).
  • Controller: add site/controllers/contact.php to handle POST: check csrf(get('csrf')), validate with invalid(), then send mail via $kirby->email() using replyTo (never use user input as from) and an email template like site/templates/emails/contact.text.php (optional contact.html.php).
  • Email config: add site/config/config.php email.transport/email.presets (current kirby://config/email is null).
  • Verify with MCP: render the page via kirby_render_page(id='contact', noCache=true); debug with mcp_dump() + kirby_dump_log_tail(traceId=...); inspect blueprint/roots via kirby_blueprint_read(id='pages/contact') and kirby://roots.

Tools (29):

kirby_blueprint_read, kirby_blueprints_index, kirby_blueprints_loaded, kirby_cache_clear, kirby_cli_version, kirby_composer_audit, kirby_collections_index, kirby_controllers_index, kirby_online, kirby_dump_log_tail, kirby_eval, kirby_generate_ide_helpers, kirby_ide_helpers_status, kirby_info, kirby_init, kirby_search, kirby_models_index, kirby_plugins_index, kirby_read_page_content, kirby_render_page, kirby_roots, kirby_routes_index, kirby_run_cli_command, kirby_runtime_install, kirby_runtime_status, kirby_snippets_index, kirby_templates_index, kirby_tool_suggest, kirby_update_page_content

Resources (12):

kirby://commands, kirby://composer, kirby://extensions, kirby://fields, kirby://fields/update-schema, kirby://glossary, kirby://hooks, kirby://info, kirby://prompts, kirby://roots, kirby://sections, kirby://tools

Resource templates (12):

kirby://blueprint/{encodedId}, kirby://cli/command/{command}, kirby://config/{option}, kirby://extension/{name}, kirby://field/{type}, kirby://field/{type}/update-schema, kirby://glossary/{term}, kirby://hook/{name}, kirby://page/content/{encodedIdOrUuid}, kirby://prompt/{name}, kirby://section/{type}

Prompts (7):

kirby_project_tour, kirby_debug_render_trace, kirby_scaffold_page_type, kirby_content_migration_assistant, kirby_ide_support_boost, kirby_upgrade_kirby, kirby_performance_audit

:christmas_tree::wrapped_gift: Merry Christmas and happy coding.

7 Likes
2

V1.1.0 adds…

:up_arrow: Updated MCP PHP SDK dependency to mcp/sdk v0.2.2.

:sparkles: Added SIGINT/SIGTERM handling for graceful stdio server shutdown.

:sparkles: Added Mago tool detection to the composer audit (carthage-software/mago or mago binary).

:sparkles: Added kirby_online_plugins tool to search the official Kirby plugin directory and optionally fetch plugin details as markdown.

:sparkles: Added runtime tools (kirby_read_site_content, kirby_read_file_content, kirby_read_user_content, kirby_update_site_content, kirby_update_file_content, kirby_update_user_content) plus resources (kirby://site/content, kirby://file/content/{encodedIdOrUuid}, kirby://user/content/{encodedIdOrEmail}) and blueprint update-schema guides.

:sparkles: Added KB resources kirby://kb and kirby://kb/{path} to list and read bundled knowledge base documents – 216 knowledge base docs in total.

:sparkles: Added the Panel development KB (kb/panel/) with kirbyup + kirbyuse focus for better extension DX.

3

v1.2.0 adds…

4

v1.2.1 adds…

  • :sparkles: kirby://uuid/new resource so Agents can generate UUIDS more easily following the hints via the knowledge base documents.
5

v1.3.0 adds…