kirby_blueprint_readLABSCO SUMMARY
Two servers in one package, and the boundary between them is deliberate.
The global reference mode answers Kirby questions and cannot touch a project; the project-local mode can read and write but requires confirmation for every mutation, keeps PHP evaluation off unless you enable it, and runs CLI commands only from an allowlist. Running both, with the reference server always on and the project server only where needed, is the setup the docs point at.
What it is
A CLI-first server for composer-based Kirby projects. It reads the project's structure, talks to a real Kirby runtime, and ships a local knowledge base of Kirby concepts so the agent does not have to guess at the framework.
What you get
- Inventory of the project: blueprints, templates, snippets, collections, controllers, models, plugins, routes and roots
- Content read and written for pages, files, users and the site, with writes behind an explicit confirmation
- A page rendered by the real runtime, returning HTML and errors, with a trace id you can use to pull the debug dumps for that render
- A bundled knowledge base searched locally, with fallbacks to the official Kirby docs and the plugin directory when it is not enough
- Kirby CLI commands run behind an allowlist, plus runtime install and status checks
- IDE helper generation and a status report on missing type hints
- Query-language evaluation and PHP evaluation, both gated - evaluation is off by default
Requirements
A composer-based Kirby project - other setups are out of scope, because much of this runs through the Kirby CLI. Add the package as a dev dependency, run the install command, and start it from the project root. There is also a projectless global reference mode for docs research, which deliberately cannot inspect or change any project. The current inventory is 37 tools, 15 resources, 15 resource templates and 216 knowledge-base articles. HTTP transport is off by default and must never be exposed without bearer-token authorisation.
Setup effort
Follow the published steps — composer require bnomei/kirby-mcp --dev
USE CASES
01
Planning a feature against the real project
Ask for a plan; the agent reads the roots, blueprints, templates and controllers that exist rather than assuming a conventional layout.
02
Debugging a page that renders wrong
Render it through the runtime for a trace id, then tail the dump log for that render to see the objects involved.
03
Answering a Kirby question without leaving the editor
Search the bundled knowledge base first, and only fall back to the official docs or the plugin directory when it comes up short.
04
Changing page content safely
Read the current content, then write the update with the confirmation flag - and consult the field update schema for the payload shape.
05
Keeping a risky tool out of reach
Leave PHP evaluation disabled and extend the CLI allowlist only for the commands you actually want run.
37 tools
Listed in project docs. Your client may show a different list.
kirby_blueprints_indexkirby_blueprints_loadedkirby_cache_clearkirby_cli_versionkirby_composer_auditkirby_collections_indexkirby_controllers_indexkirby_onlinekirby_online_pluginskirby_dump_log_tailkirby_evalkirby_query_dotkirby_generate_ide_helperskirby_ide_helpers_statuskirby_infokirby_initkirby_searchkirby_models_indexkirby_plugins_indexkirby_read_file_contentkirby_read_page_contentkirby_read_site_contentkirby_read_user_contentkirby_render_pagekirby_rootskirby_routes_indexkirby_run_cli_commandkirby_runtime_installkirby_runtime_statuskirby_snippets_indexkirby_templates_indexkirby_tool_suggestkirby_update_file_contentkirby_update_page_contentkirby_update_site_contentkirby_update_user_contentBEFORE YOU INSTALL
What to know first
Tools you get
37 tools named in the project's documentation.
Requires
- PHP 8.2+
- Kirby 5
- Composer
INSTALLATION
Connect your client
Server setup
TERMINAL
composer require bnomei/kirby-mcp --dev
vendor/bin/kirby-mcp install
vendor/bin/kirby-mcpMCP Clients
Cursor
Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). The kirby-reference server needs the global install first: composer global require bnomei/kirby-mcp.
CURSOR · JSON
{
"mcpServers": {
"kirby-reference": {
"command": "kirby-mcp",
"args": [
"--global"
]
},
"kirby-project": {
"command": "<YOUR_PATH_TO_KIRBY_PROJECT>/vendor/bin/kirby-mcp"
}
}
}Claude Code
CLAUDE CODE · TERMINAL
claude mcp add kirby -- vendor/bin/kirby-mcpCodex
CODEX · TERMINAL
codex mcp add kirby -- vendor/bin/kirby-mcpClaude.ai, Claude Desktop
This block goes in your Kirby project's .kirby-mcp/mcp.json, not in Claude. Register KirbyMcpRoutes::routes(), enable the config below, then add a Claude custom connector with your site's MCP server URL (for example <YOUR_SERVER_URL>/mcp).
JSON
{
"http": {
"enabled": true,
"path": "/mcp",
"allowedOrigins": [
"https://claude.ai"
],
"auth": {
"mode": "oauth",
"scopes": [
"kirby-mcp:read",
"kirby-mcp:runtime",
"kirby-mcp:write",
"kirby-mcp:execute",
"kirby-mcp:admin"
]
},
"oauthProvider": {
"enabled": true,
"path": "/mcp/oauth",
"consent": "snippet",
"role": "admin"
}
}
}Any MCP client — stdio
ANY MCP CLIENT — STDIO · TERMINAL
vendor/bin/kirby-mcp --project=<YOUR_PATH_TO_KIRBY_PROJECT>
