The UmbSocial MCP Server
The UmbSocial MCP server lets an AI assistant, such as Claude, Cursor or GitHub Copilot in VS Code, work with UmbSocial on your own site. The assistant can read your calendar, channels, schedule and campaigns, and write draft posts for you. A person reviews every draft in the backoffice before it can go on the calendar.
It runs on your computer, started by the assistant’s app, and signs in to your site as an Umbraco API user. It uses only UmbSocial’s management API, so it can do no more than that API user’s permissions allow.
This isn’t the same as the docs MCP server, which only searches these docs. You can connect both.
What an assistant can and can’t do
Section titled “What an assistant can and can’t do”An assistant using this server can:
- read the edition, the channels and their limits, posts (by time, status, channel, campaign, page or tag), a post’s history, views and interactions, the posting schedule, free slots and campaigns;
- write drafts: check a post against its channels’ limits, create, change and delete drafts, read a link card, and create a campaign;
- tie a draft to a page, with a delay after the page goes live, so a person can later choose When the page goes live (Posting from pages);
- with UmbSocial Pro: submit a draft for approval, start a draft from a template, set a post’s tags and UTM values, and read saved hashtags, short links and their clicks.
It can’t:
- put a post on the calendar. Its tools save drafts only, and the site would refuse anything else (
ai.needs_review): every post an API user writes is written with AI, and an API user never counts as a reviewer, whatever its permissions. A person reviews the post and schedules it, or approves it; - change or delete a post that is on the calendar or already sent. The server refuses before sending any change (
post.not_draft); - change channels, the posting schedule, templates, the list of tags or saved hashtags, or any other setting;
- use UmbSocial AI’s drafting or rewriting: the assistant is already the one writing.
Changing a post through the server also clears any earlier review of it, so a person reviews it again.
Two groups of tools are off by default: approving and returning posts, and retrying a channel or marking it as published. See MCP server configuration.
What you need
Section titled “What you need”- Node.js 22.3 or later on the computer that runs the assistant.
- An Umbraco 17 site with UmbSocial. On a site with Pro licensed, the Pro tools appear too.
- An API user in a user group set up as below.
1. Make a user group
Section titled “1. Make a user group”In Users › User groups, create a group for assistants, for example “UmbSocial assistants”:
- Under Sections, add UmbSocial. Add Content and Media too if the assistant should tie posts to pages or add images.
- In the UmbSocial box, turn on View and Write. Start with these two: they’re enough to read the calendar and write drafts. Add others only when you need them (see MCP tools for what each tool needs). Permissions explains each one.
- If you added Content and Media, choose a document start node and a media start node, and give the group Umbraco’s Browse permission on the pages it may use. Without Browse, tying a post to a page is refused (
page.no_access).
2. Make an API user
Section titled “2. Make an API user”- In Users, choose Create › API user, and add it to the group.
- Add client credentials to the user. Umbraco requires the client ID to start with
umbraco-back-office-. Copy the secret now: it isn’t shown again.
Give each person their own API user. Everyone using one API user shares its drafts, which all belong to that one user, so each person can change and delete the others’. They share its rate limits too.
3. Connect your assistant
Section titled “3. Connect your assistant”The server needs three values: the site’s address and the API user’s client ID and secret. Keep the secret out of files you commit; each example below reads it from your environment or asks for it.
Pin the version you’ve checked, as these examples do, rather than taking whatever is newest.
Claude Code (.mcp.json in your project)
{ "mcpServers": { "umbsocial": { "command": "npx", "args": ["-y", "@umbhost/umbsocial-mcp@1.0.0-beta1"], "env": { "UMBRACO_BASE_URL": "https://www.example.com", "UMBRACO_CLIENT_ID": "umbraco-back-office-social-assistant", "UMBRACO_CLIENT_SECRET": "${UMBSOCIAL_CLIENT_SECRET}" } } }}Claude Code fills in ${UMBSOCIAL_CLIENT_SECRET} from your environment. On Windows, run npx through cmd: "command": "cmd" and "args": ["/c", "npx", "-y", "@umbhost/umbsocial-mcp@1.0.0-beta1"].
Claude Desktop (claude_desktop_config.json, opened from Settings › Developer › Edit Config)
{ "mcpServers": { "umbsocial": { "command": "npx", "args": ["-y", "@umbhost/umbsocial-mcp@1.0.0-beta1"], "env": { "UMBRACO_BASE_URL": "https://www.example.com", "UMBRACO_CLIENT_ID": "umbraco-back-office-social-assistant", "UMBRACO_CLIENT_SECRET": "your-client-secret" } } }}This file is in your user profile, not in a project, so the secret is written into it. Don’t copy it anywhere it could be shared.
Cursor (.cursor/mcp.json)
{ "mcpServers": { "umbsocial": { "command": "npx", "args": ["-y", "@umbhost/umbsocial-mcp@1.0.0-beta1"], "env": { "UMBRACO_BASE_URL": "https://www.example.com", "UMBRACO_CLIENT_ID": "umbraco-back-office-social-assistant", "UMBRACO_CLIENT_SECRET": "${env:UMBSOCIAL_CLIENT_SECRET}" } } }}VS Code (.vscode/mcp.json), which asks for the secret the first time the server starts:
{ "inputs": [ { "type": "promptString", "id": "umbsocial-client-secret", "description": "UmbSocial API user's client secret", "password": true } ], "servers": { "umbsocial": { "type": "stdio", "command": "npx", "args": ["-y", "@umbhost/umbsocial-mcp@1.0.0-beta1"], "env": { "UMBRACO_BASE_URL": "https://www.example.com", "UMBRACO_CLIENT_ID": "umbraco-back-office-social-assistant", "UMBRACO_CLIENT_SECRET": "${input:umbsocial-client-secret}" } } }}Every other setting, such as turning tools off, is in MCP server configuration.
A local site with a self-signed certificate
Section titled “A local site with a self-signed certificate”The site’s address must use https. Plain http is allowed only for localhost, 127.0.0.1 and [::1].
A local site’s development certificate has to be trusted by Node.js. Either point NODE_EXTRA_CA_CERTS at the certificate, saved in PEM format, or, if the certificate is already trusted by your operating system, add --use-system-ca to NODE_OPTIONS (Node.js 22.15 or later).
Start on a staging site
Section titled “Start on a staging site”Connect the assistant to a staging copy of your site first, and try what you plan to ask of it there. Its drafts can’t go out on their own, but a staging site lets you see what it writes, and what each permission lets it do, before it works on your live calendar.
Check that it works
Section titled “Check that it works”Ask the assistant which UmbSocial edition the site has. It answers with get-social-edition, which also lists the API user’s UmbSocial permissions.
- If the group has no UmbSocial section, that is the only tool, and its answer says to add the section. Restart the assistant after changing the group: the server reads the API user’s permissions when it starts.
- If the site’s address or the credentials are wrong, the server stops at once, with a message in the assistant’s MCP log.
Reviewing what it writes
Section titled “Reviewing what it writes”Drafts written through the server carry the AI draft, needs review tag. Open one, check it, and choose Review and schedule, or, with approvals on, approve it (Approvals). With Pro and approvals on, the assistant can submit a draft for approval itself, so it waits in the approvers’ queue.
Security
Section titled “Security”- The site decides. The site checks the API user’s permissions, the AI review and the licence on every call. The server adds a few checks of its own, such as leaving posts on the calendar alone, and hides the tools the API user can’t use, so the assistant doesn’t try them. Those help, but the site’s checks are the protection.
- Secrets never appear in the assistant’s tool results, in errors or in the server’s log. To revoke access, remove the API user’s client credentials or disable the user.
- The site’s content is data. Post text, link cards and history were written by people or fetched from the web, and an assistant reads them as it reads anything else. Text in them can try to steer the assistant. Nothing it writes can go out without a person, so review what it drafts.
- Media and pages. To find images and pages, the server starts Umbraco’s own CMS Developer MCP beside it, read-only, as the same API user, and registers only eight of its tools, which browse and search media and documents. Their names start with
cms--. It is installed with the server, pinned to an exact version with every package beneath it fixed by the server’s published shrinkwrap, so nothing is downloaded when the server starts.DISABLE_MCP_CHAINING=trueturns it off; see MCP server configuration. - Confirmations.
delete-post,approve-post,retry-post-targetandmark-post-target-publishedcan’t be undone. When the assistant’s client can ask, they ask you first. When it can’t, they run only if the assistant passesconfirm: true, which it should do only after you have said yes; otherwise they’re refused withconfirmation.required. - No
.envfrom your project. The server never reads a.envfile from the folder it starts in, which is usually your project. SetUMBSOCIAL_ENV_FILEto a file’s full path to keep the settings there. - An assistant with a shell. The server’s own checks (the tools that are off by default, the confirmations, the tool filters) don’t hold against an assistant that can run commands, such as Claude Code: it can read the client secret from its environment and call the site’s API itself. Against such an assistant only the site’s checks hold, so give the API user’s group only the permissions you’d give the assistant.
- The site’s final address. The token request follows redirects, and a 307 or 308 sends the client secret again to the new address. Set
UMBRACO_BASE_URLto the address the site answers on, with no redirect from apex towwwor the like.