MCP Tool Reference
Chinaski ships an MCP (Model Context Protocol) server that exposes your CMS’s content, blocks, media, build, theme, and form tools to Claude Code and other MCP clients.
Connecting
The MCP server talks to your CMS’s REST API, so the CMS must be running. You need an API key with write permission (Admin → Settings → API Keys), then set two variables for the server:
CHINASKI_API_URL: base URL of your CMS (for local instance 1:http://localhost:3001)CHINASKI_API_KEY: your API key
The server version is 1.1.0 and speaks JSON-RPC 2.0 over stdio. A systemd unit (chinaski-mcp@1) is included in deploy/ to run it with automatic restarts and structured logs written to logs/mcp-server.log.
Logs: the server writes structured logs with daily rotation and keeps the most recent 7 daily logs.
Retries: calls to the CMS REST API retry up to 3 times with exponential backoff (1s, 2s, 4s) when the CMS responds with rate-limiting (429), unavailable (503), or other 5xx errors, or when the request times out. ping returns server status, version, uptime, and the CMS health check result.
Content tools
Enumerated below as tool tables. The tables list each tool’s name and what it does.
Pages and posts
| Tool | What it does |
|---|---|
list_pages / list_posts | List content. Returns a slim list (the body field is omitted). limit up to 1000, default 50; filter by language. |
get_page / get_post | Fetch one by ID. Full object or 404. |
create_page / create_post | Create content. Use {{block:name}} in the body to embed blocks. Pages support template override (e.g. landing.tt), parent_id for the page tree, and schedule_publish_at / unpublish_at (ISO 8601, site local time). Posts accept a category slug, comma-separated tags, a published_at override, and scheduling. |
update_page / update_post | Update by ID. Only the fields you supply change. |
delete_page / delete_post | Soft delete. |
Blocks
| Tool | What it does |
|---|---|
list_blocks / get_block | Browse blocks (structured content_json is omitted in list results). |
create_block | Create a block; the unique name is what you reference in bodies via {{block:name}}. Valid types: accordion, columns, cta, embed, form, gallery, hero, image, newsletter, promo, quote, stat, table, testimonial, text, video. Styling options include background/text/button colors, border width, padding, margin, and overlay color/opacity (0.0–1.0). |
bulk_create_blocks | Create many blocks in one call; per-item errors are returned alongside successes. |
update_block / delete_block | Modify or soft-delete. |
Snippets and categories
| Tool | What it does |
|---|---|
list_snippets / get_snippet / create_snippet / update_snippet / delete_snippet | Manage code snippets injected into the site head or body. Set is_global to inject on every page; set privacy_sensitive to mark a snippet as requiring consent before loading. |
list_categories | List post categories. |
get_category / create_category / update_category / delete_category | Manage categories by ID (deletes are soft). |
Build
| Tool | What it does |
|---|---|
trigger_build | Trigger a static site rebuild. Returns dispatched, busy, or missing. |
get_build_status | Returns the last build time and whether a build is currently running. |
The build runs asynchronously: after creating or updating content, call trigger_build, then poll get_build_status, build_in_progress: true means it is still running.
Forms
| Tool | What it does |
|---|---|
list_forms / get_form | List and fetch forms (webhook/notification endpoints are excluded from these results). |
create_form | Create a form with a name and slug (the slug is used in embeds and API references). |
update_form | Update form settings: for example notify_email, reply_to_field, or blocked_countries. Note: webhook URLs, thank-you URL, and the webhook secret are not writable through these tools. |
delete_form | Soft delete. |
list_form_fields / create_form_field / update_form_field / delete_form_field | Manage form fields. Field types: text, email, tel, textarea, select, checkbox, address, radio, checkboxes, file. Field names are sanitized to lowercase letters, digits, and underscores. Options for select/radio/checkboxes are newline-separated. Conditional display is set with condition_field + condition_value; layout width is full or half. |
Navigation
| Tool | What it does |
|---|---|
list_nav_items / create_nav_item / update_nav_item / delete_nav_item | Manage navigation menus. Filter by slot (header or footer); is_external opens in a new tab; parent_id nests items. |
Media and documents
| Tool | What it does |
|---|---|
list_media | Paginated media library listing, 50 per page. |
get_media | Media details: file, MIME type, size, alt text, folder, URL, dimensions, caption, credit, and timestamps. |
update_media | Update metadata only: alt text, caption, credit, folder. |
list_documents | Published PDFs and downloadable files, including download counts. |
get_document | Fetch one document by slug. |
Themes
| Tool | What it does |
|---|---|
get_theme_guide | Returns the complete Chinaski theme authoring reference as Markdown. Recommended reading before generating any theme files. |
list_themes / clone_theme | List themes, or clone one as a starting point (default source: sbs). |
list_theme_files / read_theme_file | Browse and read a theme’s .tt template files. |
write_theme_file | Create or overwrite a template file. Content is security-scanned and syntax-validated on the server side before it is accepted. |
delete_theme | Delete a theme and all its files; only non-active themes can be deleted. |
Design briefs
| Tool | What it does |
|---|---|
list_design_briefs | List uploaded design briefs (reference HTML/CSS used for visual direction). |
read_design_brief_file / list_design_brief_files | Read the files inside a brief by its ID. |
Higher-level tools
These combine several CMS operations into one call:
| Tool | What it does |
|---|---|
create_post_with_blocks / create_page_with_blocks | Create content plus its blocks in one call; each block’s {{block:name}} shortcode is appended to the body automatically. |
append_block_to_page / append_block_to_post | Append {{block:name}} to an existing page or post by ID or slug (ID takes precedence). |
bulk_import | Create, or with upsert: true create-or-update, many pages or posts from an array, matched by slug + language and applied atomically per item. Optionally triggers a build. |
bulk_update | Update many pages or posts by ID. |
bulk_create_and_append_blocks | Create blocks and attach each to a page in one call. |
translate_content | Fetch a page or post and create a translated copy into a target language; you supply the translated title and body, while language-agnostic fields (featured image, author, and similar) are copied automatically. |
audit_content | Report translation completeness across pages, posts, blocks, snippets, nav items, and categories, listing items with MISSING or STALE indicators. Base language defaults to en. |
auto_create_translations | Create translation stubs for a content item: the source record is copied into each missing language as an unpublished draft. |
submit_job / get_job_status | For very large operations (200+ items), submit an async batch job (bulk page/post upserts or block creation) and poll its progress. |
Discovering your site’s content
| Tool | What it does |
|---|---|
get_site_context | Site configuration: languages, themes, block types, categories with post counts, and recent content counts. Cached briefly (5 minutes); pass refresh: true to force a re-read. |
search_content | Keyword search across pages, posts, blocks, snippets, and categories. |
get_popular_content | Recently updated pages and posts, newest first. |
get_content_gaps | Audit pages/posts for missing meta descriptions, empty bodies, or no featured image. |
get_pages_missing_block_type | Find pages that don’t reference any block of a given type (e.g. cta). |
get_orphaned_blocks | Find blocks not referenced by any page or post body. |
list_scheduled_pages / list_scheduled_posts | Content queued for future auto-publish, with local publish times. |
list_redirects | All redirects, filterable by language. |
Browsing as resources
Besides tools, the server exposes a browsable content graph through MCP resources, which lets a client read content before changing anything:
page://en/about-us: a published page by language/slugpost://en/blog/my-post: a blog post by language/slugblock://en/hero-home: a block by language/nametheme://library/page.tt: a theme template file
Use resources/list, resources/read, and resources/templates/list. Snippets cannot be read by URI; use the snippet tools instead.
Canned prompts
prompts/list offers ready-made prompts:
- Write a blog post in the style of the most recently updated article
- Audit all pages and posts for missing meta descriptions
- List content with no featured image
- Identify the most recently updated pages missing translations
- Find blocks not referenced by any page or post body
- Draft a new landing page using the site default language
Session history
Most create/update/delete tools accept an optional context argument (a session ID). When provided, each call is recorded and can be retrieved later with get_session_history. Session records expire automatically after 24 hours. Passwords, secrets, and API keys are redacted before anything is stored.
Efficient working patterns
- For many items at once, prefer bulk tools:
bulk_import(withupsert: true),bulk_update, orcreate_post_with_blocks/create_page_with_blocksinstead of long chains of single creates. - Use
submit_jobfor operations of 200+ items, then pollget_job_status. - After changing content, remember the site is static: the rebuild only happens when you call
trigger_build.