Skip to main content
Glama
Plone MCP Server

Plone MCP Server

Official
by plone

Plone MCP Server

Talk to your Plone website instead of clicking through it. Plone MCP lets AI assistants like Claude create and edit pages, publish content, search the site, and manage translations on your behalf, in plain language - no coding required to use it, and nothing to change on your Plone site to enable it.

It's built on the Model Context Protocol (MCP), an open standard that lets AI assistants safely connect to external tools and data. Plone MCP exposes Plone's REST API as a set of MCP tools, so any MCP-compatible client - Claude Desktop, Claude Code, and others - can drive your site, and developers can script, automate, or build on top of the same tools.

Quickstart

Requires Node.js 22+. Add this to Claude Desktop's config file, then restart Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "plone": {
      "command": "npx",
      "args": ["-y", "@plone/mcp"]
    }
  }
}

Now ask Claude to connect to your Plone site, e.g. "Connect to https://demo.plone.org as admin/admin".

Related MCP server: optimizely-cms-mcp

Prerequisites

  • Node.js 22+ - Required to run the server (^20.19.0 || >=22.12.0; install: brew install node on macOS or from nodejs.org)

  • Plone 6.0+ site with REST API - The CMS you'll be connecting to

pnpm is only needed if you want to clone the repo and develop locally (see Local Development). The recommended setup below uses npx and doesn't require cloning anything.

Transports

The server ships two entry points:

  • STDIO (plone-mcp bin / dist/stdio-server.js) - for local MCP clients such as Claude Desktop.

  • HTTP (dist/http-server.js) - a streamable-HTTP server with per-session state, listening on PORT (default 3001) at /mcp. Start it with make start.

Quick Start using Claude Desktop as an example

The @plone/mcp package is published on npm, so there's nothing to install or build - npx fetches and runs it on demand.

  1. Configure Claude Desktop

Add to Claude's configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

With environment variables (optional):

{
  "mcpServers": {
    "plone": {
      "command": "npx",
      "args": ["-y", "@plone/mcp"],
      "env": {
        "PLONE_BASE_URL": "https://demo.plone.org",
        "PLONE_USERNAME": "admin",
        "PLONE_PASSWORD": "admin"
      }
    }
  }
}

Without environment variables (useful if you connect to different Plone sites and prefer to pass credentials per session via plone_configure):

{
  "mcpServers": {
    "plone": {
      "command": "npx",
      "args": ["-y", "@plone/mcp"]
    }
  }
}
  1. Restart Claude Desktop

  2. Connect to Plone

Call plone_configure once per session:

// Using environment variables
plone_configure({});

// OR providing credentials/token directly to the LLM
plone_configure({
  baseUrl: "https://demo.plone.org",
  username: "admin",
  password: "admin",
});

plone_configure({
  baseUrl: "https://demo.plone.org",
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
});

Note: Arguments take precedence over environment variables.

Local Development

Clone the repo if you want to modify the server, debug it, or run it with the MCP Inspector:

git clone https://github.com/plone/plone-mcp.git
cd plone-mcp
make install
make build

Point Claude Desktop at your local build instead of the npx command:

{
  "mcpServers": {
    "plone": {
      "command": "node",
      "args": ["/absolute/path/to/plone-mcp/dist/index.js"]
    }
  }
}

Development commands:

# Install the dependencies
make install

# Build for production (compiles TypeScript and copies blocks.json)
make build

# Run the HTTP server / the STDIO server from the build
make start
make stdio

# Debug with the MCP Inspector
make inspector

# Tests (Vitest)
make test-all       # everything
make test           # unit tests only
make test-coverage  # with coverage

# Static checks
make lint           # ESLint over src/ and __tests__/
make format         # ESLint with --fix
make type-check     # tsc over sources and tests

Run make help to list every available target.

Core Features

  • Content Management: CRUD operations on all Plone content types

  • Block System: Create and manage Volto blocks

  • Search: Full-text search with filtering and sorting

  • Workflow: Manage publication states and transitions

  • Site Info: Access content types, vocabularies, and site configuration

Essential Tools

Tool

Description

Example

plone_configure

Connect to Plone (call once per session)

plone_configure({baseUrl, username, password}) or plone_configure({}) for env vars

plone_get_content

Get content by path

plone_get_content({path: "/news"})

plone_create_content

Create new content

plone_create_content({parentPath: "/", type: "Document", title: "Page"})

plone_update_content

Update existing content

plone_update_content({path: "/page", title: "New Title"})

plone_delete_content

Delete content

plone_delete_content({path: "/old-page"})

plone_copy_content

Copy content into a container

plone_copy_content({parentPath: "/archive", source: "/news"})

plone_move_content

Move content into a container

plone_move_content({parentPath: "/archive", source: "/old-page"})

plone_search

Search content

plone_search({query: "news", portal_type: ["Document"]})

plone_transition_workflow

Change workflow state

plone_transition_workflow({path: "/page", transition: "publish"})

plone_get_navigation_tree

Get hierarchical site structure

plone_get_navigation_tree({root_path: "/", depth: 2})

plone_get_translation

List translations of a content item

plone_get_translation({path: "/en/my-page"})

plone_link_translation

Link existing content as a translation

plone_link_translation({path: "/en/my-page", id: "/de/meine-seite"})

plone_unlink_translation

Remove a translation link

plone_unlink_translation({path: "/en/my-page", language: "de"})

plone_create_working_copy

Check out content into a working copy

plone_create_working_copy({path: "/my-document"})

plone_get_working_copy

Show working copy relationship and lock

plone_get_working_copy({path: "/my-document"})

plone_checkin_working_copy

Check in a working copy

plone_checkin_working_copy({path: "/working_copy_of_my-document"})

plone_cancel_working_copy

Discard a working copy

plone_cancel_working_copy({path: "/working_copy_of_my-document"})

Block Management

Creating Content with Blocks

// 1. Prepare blocks (60-second TTL - meant to be used inmediatly before content creation/editing)
plone_create_blocks_layout({
  blocks: [
    {
      type: "text",
      data: { text: "Welcome to our site!" },
    },
    {
      type: "teaser",
      data: {
        href: "/about",
        title: "Learn More",
        description: "Discover what we do",
      },
    },
  ],
});

// 2. Create content (within 60 seconds), the previously prepared blocks will automatically be included in the request
plone_create_content({
  parentPath: "/",
  type: "Document",
  title: "Homepage",
});

Managing Individual Blocks

// Add a single block
plone_add_single_block({
  path: "/homepage",
  blockType: "text",
  blockData: { text: "New paragraph" },
  position: 1,
});

// Update a block
plone_update_single_block({
  path: "/homepage",
  blockId: "51176ead-7b59-402d-9412-baed46821b36", // Get ID from plone_get_content
  blockData: { text: "Updated text" },
});

// Remove a block
plone_remove_single_block({
  path: "/homepage",
  blockId: "51176ead-7b59-402d-9412-baed46821b36",
});

Available Block Types

  • text: Rich text content

  • teaser: Link preview card with image

  • __button: Call-to-action button

  • separator: Visual divider line

Use plone_get_block_schemas() to see all block types and their properties.

Common Workflows

Create and Publish a Page

// Configure connection
plone_configure({
  baseUrl: "https://mysite.com",
  username: "editor",
  password: "secret",
});

// Create with blocks
plone_create_blocks_layout({
  blocks: [{ type: "text", data: { text: "Article content..." } }],
});
plone_create_content({
  parentPath: "/news",
  type: "News Item",
  title: "Breaking News",
});

// Publish
plone_transition_workflow({
  path: "/news/breaking-news",
  transition: "publish",
});

Copy and Move Content

// Copy one or more items into another folder (originals stay in place)
plone_copy_content({
  parentPath: "/archive",
  source: ["/news/breaking-news", "/news/annual-report"],
});

// Move an item, removing it from its current location
plone_move_content({
  parentPath: "/archive",
  source: "/old-page",
});

Search and Filter

plone_search({
  query: "annual report",
  portal_type: ["Document", "File"],
  review_state: ["published"],
  sort_on: "modified",
  sort_order: "descending",
  b_size: 10,
});

Important Notes

⚠️ Prepared blocks expire after 60 seconds - Always call plone_create_blocks_layout immediately before creating/updating content.

⚠️ Configure once per session - Run plone_configure once at the start of each session before using other tools. Once configured, you can use all other tools without reconfiguring.

Troubleshooting

Issue

Solution

command not found when using npx

Make sure the args in your config use plone-mcp as the binary name (not plone-mcp-server) — this was renamed in the package.

"Plone client not configured"

Run plone_configure once at the start of your session

"Block not found"

Use plone_get_content to get valid block IDs

Connection errors

Verify Plone URL and credentials are correct

Blocks not applied

Call plone_create_blocks_layout immediately before create/update (60s TTL)

TypeScript errors during local build

Run make install to ensure all dependencies are installed

Resources

License

MIT

Available Tools

22 tools
plone_add_single_blockAdd Single BlockA

Adds a single new block to an existing content item without replacing other blocks. Specify the block type, data, and optional position. Example: plone_add_single_block({path: '/my-page', blockType: 'text', blockData: {text: 'New paragraph'}})

Inputs: path (required), blockType (required), blockData (required), position.

plone_configureConfigure Plone ConnectionA

Establishes and authenticates the connection to a Plone CMS. Must be called once per session before other tools can be used. Configuration can be provided via arguments or environment variables (PLONE_BASE_URL, PLONE_USERNAME, PLONE_PASSWORD, PLONE_TOKEN). Arguments take precedence over environment variables. To use environment variables only, call with an empty object: plone_configure({}). Example with arguments: plone_configure({baseUrl: 'https://demo.plone.org', username: 'admin', password: 'secret'}).

Inputs: baseUrl, username, password, token.

plone_create_blocks_layoutPrepare Blocks LayoutA

Prepares a complete block structure in memory (valid for 60 seconds). This structure is then used by the next immediate call to plone_create_content or plone_update_content. Use plone_get_block_schemas to learn what data each block type needs. The text displayed by the Title block is automatically managed by Plone, DO NOT add it in the block's data. Example: plone_create_blocks_layout({blocks: [{type: 'title'},{type: 'slate', data: {text: 'Hello World'}}]})

Inputs: blocks (required).

plone_create_contentCreate Plone ContentA

Creates a new content item (e.g., a page or news article) in Plone. To add complex block-based content, first prepare the structure with plone_create_blocks_layout, then call this tool. Example: plone_create_content({parentPath: '/', type: 'Document', title: 'My Page', description: 'A sample page'})

Inputs: parentPath (required), type (required), title (required), description, +4 more.

plone_create_userCreate Plone UserA

Creates a new user in the Plone site. Requires Manager role or self-registration to be enabled. Example: plone_create_user({username: 'jdoe', password: 'secret', email: 'jdoe@example.com', fullname: 'John Doe', roles: ['Contributor']})

Inputs: username (required), password (required), email, fullname, +5 more.

plone_delete_contentDelete Plone ContentA

Permanently deletes a content item from Plone using its path. Example: plone_delete_content({path: '/old-content'})

Inputs: path (required).

plone_get_block_schemasGet Block SchemasA

Lists all available Volto block types (e.g., 'slate', 'teaser', 'button') and their required data schemas. If no block type specified, the tool returns all blocks schemas. Essential for understanding how to construct blocks. Example: plone_get_block_schemas({blockType: 'teaser'})

Inputs: blockType.

plone_get_contentGet Plone ContentA

Retrieves the full JSON data for a single content item from Plone using its path. Example: plone_get_content({path: '/news/latest-update'})

Inputs: path (required), expand.

plone_get_site_infoGet Site InformationA

Retrieves top-level information and metadata about the connected Plone site, such as available languages and Plone version.

Inputs: no named parameters.

plone_get_translationGet Translations of a Content ItemB

Retrieves all available translations for a content item , identified by its '@id' (URL). Example: plone_get_translation({path: '/en/my-page'})

Inputs: path (required).

plone_get_typesGet Content TypesA

Lists all available content types that can be created in the Plone site (e.g., 'Document', 'Event').

Inputs: no named parameters.

plone_get_type_schemaGet Content Type SchemaA

Gets the full JSON schema for a specific content type, including all fields, their types, required status, and validation rules. Use this to understand what fields are available when creating or updating content. Example: plone_get_type_schema({contentType: 'Document'})

Inputs: contentType (required).

plone_get_vocabulariesGet Vocabulary ValuesA

Fetches the allowed values for a specific field, such as a list of categories or tags. Useful for finding valid inputs for content fields. Example: plone_get_vocabularies({vocabulary: 'plone.app.vocabularies.Keywords'})

Inputs: vocabulary (required), title, token.

plone_get_workflow_infoGet Workflow InformationA

Shows the current workflow state (e.g., 'Published', 'Private') and available transitions for a content item. Example: plone_get_workflow_info({path: '/my-document'})

Inputs: path (required).

plone_remove_single_blockRemove Single BlockB

Deletes a single block from a content item, identified by its block ID. Example: plone_remove_single_block({path: '/my-page', blockId: 'abc123'})

Inputs: path (required), blockId (required).

plone_transition_workflowExecute Workflow TransitionA

Changes the workflow state of a content item by executing a specific transition, like 'publish' or 'submit'. Example: plone_transition_workflow({path: '/my-document', transition: 'publish'})

Inputs: path (required), transition (required), comment.

plone_update_contentUpdate Plone ContentA

Modifies an existing content item in Plone. Can update metadata (like title) and/or replace the entire block structure. Use plone_create_blocks_layout to prepare complex block updates or use the plone_add_single_block and plone_update_single_block tools for smaller changes. DO NOT edit the block structure directly. Example: plone_update_content({path: '/my-page', title: 'Updated Title'})

Inputs: path (required), title, description, blocks, +2 more.

plone_update_single_blockUpdate Single BlockB

Modifies the data of a single, existing block within a content item, identified by its block ID. Example: plone_update_single_block({path: '/my-page', blockId: 'abc123', blockData: {text: 'Updated text'}})

Inputs: path (required), blockId (required), blockData (required).

plone_update_userUpdate Plone UserA

Updates an existing user's properties in Plone. Requires Manager role or the user updating their own account. Roles are specified as an object mapping role names to booleans to add or remove them. Example: plone_update_user({userid: 'jdoe', fullname: 'Jane Doe', roles: {Editor: true, Contributor: false}})

Inputs: userid (required), email, fullname, description, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 22 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, from authentication to content creation, block manipulation, workflow, translations, and user management. No two tools overlap in function; even block-related tools (create_blocks_layout vs add_single_block) are clearly differentiated.

    Naming Consistency5/5

    All tools follow a consistent 'plone_' prefix with underscore-separated verb-noun patterns (e.g., plone_get_content, plone_create_user, plone_transition_workflow). The naming is predictable and logical throughout the set.

    Tool Count4/5

    With 22 tools, the server covers a broad range of Plone CMS operations without being excessive. The count is appropriate for the complexity of the system, though a few tools (e.g., plone_configure and plone_get_site_info) could potentially be merged.

    Completeness4/5

    The toolset provides comprehensive coverage for core workflows: content CRUD, block management, user creation/update, workflow transitions, translations, search, and schema exploration. Notable gaps include user deletion and folder manipulation (move/rename), but these are minor given the overall robustness.

    Maintenance

    ActivitySlowing
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers