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#
Sync content from another system, migrate a site, or automate maintenance.
Work on many sites by name, preview every change, and script the rest.
Let an assistant or a coding agent edit a site, within limits you set.
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.
-nanddry_run=Trueprint 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#
Learn by doing, one step at a time.
Solve a specific problem.
Look up every service, command, and setting.
Understand why it works this way.