plone-client#

One client to automate Plone, whether the operator is a developer, a shell script, or an AI agent.

plone-client is a Python library, a command line, and an MCP server for Plone sites, built on plone.restapi.

Alpha

plone-client is in alpha: its Python API and its commands can change before 1.0. Read the Changelog before you upgrade.

Try it now#

You need only uv. This command lists the top of demo.plone.org, a public site that anyone can use and that resets every night.

uvx --from "plone-client[cli]" plone-client --url https://demo.plone.org ls / -f title,review_state
[
  {
    "title": "Plone Foundation Logo",
    "review_state": null
  },
  {
    "title": "Images",
    "review_state": "published"
  },
  {
    "title": "Blocks",
    "review_state": "published"
  },
  {
    "title": "Content Types",
    "review_state": "published"
  },
  {
    "title": "Vertical Spacing",
    "review_state": "published"
  }
]

Pick your path#

🐍 Script Plone from Python

Sync content from another system, migrate a site, or automate maintenance.

Script Plone from Python
πŸ’» Manage sites from a terminal

Work on many sites by name, preview every change, and script the rest.

Manage sites from a terminal
πŸ€– Work with AI assistants

Let an assistant or a coding agent edit a site, within limits you set.

Work with assistants and coding agents

New to Plone? Get started explains what you need to know, in terms of what you already know.

Install#

uv add plone-client                            # Python library
uv tool install "plone-client[cli]"            # command line
uv tool install "plone-client[mcp,markdown]"   # assistants
pip install plone-client                       # Python library
pipx install "plone-client[cli]"               # command line
pipx install "plone-client[mcp,markdown]"      # assistants

plone-client needs Python 3.11 or later, and the markdown extra needs 3.12; see Install plone-client.

What it looks like#

Save this as demo.py; it reads the public demo site without logging in.

from plone_client import PloneClient

with PloneClient("https://demo.plone.org") as site:
    for item in site.search.iter(portal_type="Document", limit=3):
        print(item["title"])
uv run --with plone-client demo.py

With a profile, replace the URL with PloneClient.from_profile("production").

Preview publishing a folder and everything in it, on the public demo site. With -n, the command prints the request it would send, and sends nothing.

uvx --from "plone-client[cli]" plone-client --url https://demo.plone.org -n workflow /content-types publish --recursive
{
  "dry_run": true,
  "method": "POST",
  "url": "https://demo.plone.org/++api++/content-types/@workflow/publish",
  "json": {
    "include_children": true
  }
}

On your own site, name its profile instead of the URL.

plone-client -n -p production workflow /news publish --recursive

Add a site as a profile, and give your assistant this server. This is the mcpServers shape that Claude Desktop, Cursor, and most clients read; VS Code names the key servers, as Connect an assistant through the MCP server shows.

{
  "mcpServers": {
    "plone": {
      "command": "plone-client",
      "args": ["--profile", "production", "--read-only", "mcp"]
    }
  }
}

Then ask it: β€œWhich news items on the site are still private?”

Safe by design#

  • Secrets stay out of files. A profile keeps its password in the keyring of your operating system, or reads it from the environment or a command where there is no keyring; see Use the command line in scripts and CI.

  • Read-only sites stay read-only. A profile or a client can refuse every change before sending it.

  • Dry runs show the plan. -n and dry_run=True print the requests and send none of them.

  • Destructive commands ask first. Without a terminal, they need --yes.

  • Failures have names. Each kind of failure has its own exception and exit code, listed in Exceptions.

  • Plone has the last word. Every request runs with the permissions of the user you logged in as.

Protect a site from an agent puts these together for assistants.

All the documentation#

πŸš€ Tutorials

Learn by doing, one step at a time.

Tutorials
🧭 How-to guides

Solve a specific problem.

How-to guides
πŸ“– Reference

Look up every service, command, and setting.

Reference
πŸ’‘ Explanation

Understand why it works this way.

Explanation