# Kirby MCP Server - inspect blueprints/templates/plugins, interact with a real Kirby runtime, and use a bundled knowledge base **URL:** \ **Category:** Plugins\ **Tags:** v5\ **Created:** [December 24, 2025, 10:07am UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106 "2025-12-24T10:07:00Z")\ **Posts on this page:** 11\ **Page:** 1
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [December 24, 2025, 10:07am UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/1 "2025-12-24T10:07:00Z")
> I am creating posts for [my plugins](https://getkirby.com/plugins/bnomei) to make it easier to find them using the forum search and not just the docs search. ![plugin-image-kirby-mcp](https://europe1.discourse-cdn.com/flex017/uploads/getkirby/original/3X/f/1/f1fb3768f077b77baa1b76693ceeebe99211ec82.webp) # Kirby MCP [Kirby MCP is a CLI-first MCP server](https://github.com/bnomei/kirby-mcp) 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](https://modelcontextprotocol.io/docs/getting-started/intro) (Cursor, Claude Code, Codex CLI, …) and runs directly from your Kirby project - AI optimized [local knowledge base with 182 docs](https://github.com/bnomei/kirby-mcp/tree/main/kb) 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 > ℹ “ **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. ```plaintext 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` * * * 🎄🎁 Merry Christmas and happy coding. > **[GitHub - bnomei/kirby-mcp: CLI-first MCP server for composer-based Kirby CMS...](https://github.com/bnomei/kirby-mcp)** > > CLI-first MCP server for composer-based Kirby CMS projects — inspect blueprints/templates/plugins, interact with a real Kirby runtime, and use a bundled Kirby knowledge base. ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [January 1, 2026, 5:53pm UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/2 "2026-01-01T17:53:52Z")
V1.1.0 adds… ⬆ Updated MCP PHP SDK dependency to `mcp/sdk` v0.2.2. ✨ Added SIGINT/SIGTERM handling for graceful stdio server shutdown. ✨ Added [Mago](https://mago.carthage.software) tool detection to the composer audit (`carthage-software/mago` or `mago` binary). ✨ Added `kirby_online_plugins` tool to search the official Kirby plugin directory and optionally fetch plugin details as markdown. ✨ 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. ✨ Added KB resources `kirby://kb` and `kirby://kb/{path}` to list and read bundled knowledge base documents – 216 knowledge base docs in total. ✨ Added the Panel development KB (`kb/panel/`) with [kirbyup](https://kirbyup.getkirby.com/) + [kirbyuse](https://github.com/johannschopplich/kirbyuse) focus for better extension DX. ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [January 7, 2026, 3:43pm UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/3 "2026-01-07T15:43:02Z")
[v1.2.0](https://github.com/bnomei/kirby-mcp/releases/tag/v1.2.0) adds… - 🔥 Dropped prompt-driven setup guidance in favor of [Skills](https://agentskills.io). - ✨ Added [15 bundled Codex/Claude Skills](https://github.com/bnomei/kirby-mcp/tree/main/skills) and documented how to copy them into the client. ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [January 8, 2026, 2:14pm UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/4 "2026-01-08T14:14:14Z")
v1.2.1 adds… - ✨ `kirby://uuid/new` resource so Agents can generate [UUIDS](https://getkirby.com/docs/guide/uuids) more easily following the hints via the knowledge base documents. ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [January 10, 2026, 9:51pm UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/5 "2026-01-10T21:51:37Z")
v1.3.0 adds… - ✨ new `kirby_query_dot` tool to evaluate [blueprint query language](https://getkirby.com/docs/guide/blueprints/query-language) directly - ♻ improved bundled skills by following the [Claude Code Skill Best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) more closely - ♻ minor improvements to 107 knowledge base documents ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [February 24, 2026, 10:44am UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/6 "2026-02-24T10:44:55Z")
v1.4.0 adds… - ⬆ Updated MCP PHP SDK dependency to `mcp/sdk` v0.4.0. - ✨ Added MCP resource update notifications for subscribed resources after successful content writes (`kirby_update_page_content`, `kirby_update_site_content`, `kirby_update_file_content`, `kirby_update_user_content`). - ✨ Notifications use `notifications/resources/updated` and currently include only the changed resource `uri` (clients should re-read the resource for fresh content). - ✨ Subscription tracking is session-scoped and event-based (emitted after successful write tools; out-of-band file/panel edits are not detected). - ✨ Added optional client-side MCP elicitation confirmation for confirm-gated runtime tools (`kirby_update_page_content`, `kirby_update_site_content`, `kirby_update_file_content`, `kirby_update_user_content`, `kirby_eval`, `kirby_query_dot`) while keeping explicit `confirm=true` behavior and dry-run fallback. - ♻ Kept backward compatibility for update-tool `data` payloads by accepting both JSON objects and JSON-encoded object strings in tool schemas and runtime parsing. ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [May 18, 2026, 1:56pm UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/7 "2026-05-18T13:56:33Z")
v1.5.0 adds… - ⬆ Updated MCP PHP SDK dependency to `mcp/sdk` v0.5.0. v1.6.0 adds… - ♻ Fixed an input schema strictness issue - ✨ the MCP server can now also be exposed on /mcp allowing remote access for agents. see Readme on how to make it secure. ```auto [ [ 'pattern' => 'mcp', 'method' => 'GET|POST|DELETE|OPTIONS', 'action' => fn () => KirbyMcpRoute::handle(), ], ], ]; ``` ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [May 22, 2026, 3:24pm UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/8 "2026-05-22T15:24:36Z")
v1.7.0 adds… - ✨ the MCP server can now also connect to Claude Desktop/Ai (not just CLI tools) via a custom consent flow. ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [June 2, 2026, 5:15pm UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/9 "2026-06-02T17:15:35Z")
v1.8.0 adds… - ⬆ Updated MCP PHP SDK dependency to `mcp/sdk` v0.6.0. - ✨ Added MCP spec-level titles to resources and resource templates. - ✨ Added explicit HTTP MCP session TTL and SDK-backed session garbage-collection settings. - ✨ Added SDK protocol-version validation to Streamable HTTP POST and GET/SSE requests while keeping the existing auth, origin, and CORS handling authoritative. ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [June 16, 2026, 10:06am UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/10 "2026-06-16T10:06:07Z")
v1.9.0 adds… - ✨ **Global mode** : 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. Per project inspection of available templates, blueprints and any write actions etc. will require the MCP to installed as a dev dependency in the project itself. ---
**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\ **Post date:** [June 29, 2026, 12:57pm UTC](https://forum.getkirby.com/t/kirby-mcp-server-inspect-blueprints-templates-plugins-interact-with-a-real-kirby-runtime-and-use-a-bundled-knowledge-base/35106/11 "2026-06-29T12:57:47Z")
v1.10.0 - v1.10.2 add… - ✨ php binary override option - ♻ add various minor improvements and bugfixes - 🛡 improved remote MCP usage security - 🛡 config secret redaction