UmbSocial MCP server
OfficialEnables the MCP server to work against an Umbraco 17 site with UmbSocial, using an Umbraco API user for authentication and a read-only chained CMS Developer MCP to browse and search media and documents for page/media keys used in social drafts.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
UmbSocial MCP server
@umbhost/umbsocial-mcp lets an AI assistant work with UmbSocial on an Umbraco 17 site. The assistant can read the Social calendar, channels and campaigns, and write draft posts. A person reviews every draft in the Umbraco backoffice before it can go on the calendar.
It runs on your machine over stdio and signs in to the site as an Umbraco API user, using that user's client credentials. It calls only UmbSocial's own management API.
Beta. The package is a prerelease, published under npm's beta dist-tag. See CHANGELOG.md.
How it differs from the docs MCP
UmbSocial's documentation has its own MCP server at https://docs.umb.social/mcp. That one searches and reads the docs, needs no site and no sign-in, and changes nothing.
This server works on your site: it reads your posts and writes drafts as the API user you give it. Use the docs MCP to learn how UmbSocial works, and this one to work with your own Social calendar. You can connect both.
Related MCP server: SocialHive MCP Server
Requirements
Node.js 22.3 or later.
An Umbraco 17 site with UmbSocial installed. UmbSocial Pro adds more tools, such as approvals, templates and tags, when the site is licensed.
An Umbraco API user with client credentials, in a user group that has the Social section and the Social permissions you want the assistant to have. Start with View and Write.
To tie posts to pages and pick images, the group also needs the Content and Media sections, start nodes, and Umbraco's Browse permission on those pages.
Give each person their own API user. Everyone using one API user shares its drafts and its rate limits.
The full set-up is in the docs: The UmbSocial MCP server.
Configuration
For Claude Code, in .mcp.json:
{
"mcpServers": {
"umbsocial": {
"command": "npx",
"args": ["-y", "@umbhost/umbsocial-mcp@beta"],
"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 ${UMBSOCIAL_CLIENT_SECRET} from your environment, so the secret stays out of the file. The server never reads a .env file from its working directory, which is usually your project folder. To keep the settings in a file, set UMBSOCIAL_ENV_FILE to its full path; .env.example lists every variable.
Variable | Meaning |
| The site's address. It must use https; plain http is allowed only for |
| The API user's client credentials. |
| The full path of a file holding these variables, read at start. No other |
| Turns on tools that are off by default: |
|
|
| The SDK's tool filters. |
The docs have the configuration for Claude Desktop, Cursor and VS Code in The UmbSocial MCP server, every variable in MCP server configuration, and every tool in MCP tools.
A local site with a self-signed certificate
Trust the certificate; never turn TLS checks off (NODE_TLS_REJECT_UNAUTHORIZED=0). Point NODE_EXTRA_CA_CERTS at the certificate in PEM format, or, if the certificate is in your system's store, add --use-system-ca to NODE_OPTIONS. --use-system-ca needs Node.js 22.15 or later.
The chained CMS server
Posts refer to Umbraco media and pages by key, so by default this server starts Umbraco's own CMS Developer MCP alongside it, to find those keys. Its tools appear with a cms-- prefix. It runs:
read-only (
UMBRACO_READONLY=true), limited to eight tools that browse and search media and documents;as the same API user, so it sees only that user's start nodes;
from a pinned, shrinkwrapped copy:
@umbraco-cms/mcp-devis an exact dependency of this package (17.6.12), and the publishednpm-shrinkwrap.jsonfixes every package beneath it, so you install the versions this release was tested with. It is started with Node from where it was installed; nothing is downloaded when the server starts.
This server registers only those eight tools, whatever the chained server lists, and logs the name of any other tool it drops.
DISABLE_MCP_CHAINING=true turns it off. The Social tools still work; the assistant then needs media and page keys from you.
Safety
The site enforces the AI rule. Every post an API user creates or changes is marked as written with AI, and an API user never counts as a reviewer. A person must review an AI-written post in the backoffice before it can be scheduled. No tool can get round this, and no tool result suggests trying.
Drafts only. The writing tools save drafts.
update-post,delete-post,set-post-utmandset-post-tagschange only drafts and posts awaiting approval: a post on the calendar, or one already sent, is left as a person left it.Confirmations.
delete-post,approve-post,retry-post-targetandmark-post-target-publishedare marked destructive, and ask the person first when the client can ask. When it can't, they go ahead only if the assistant passesconfirm: true, which it should do only after the person has said yes; otherwise they're refused withconfirmation.required.Off by default. The
approveandresolvetools act on review and on live networks, so they're registered only whenUMBSOCIAL_ENABLE_SLICESnames them (naming one inUMBRACO_INCLUDE_TOOLSisn't enough), and only for a user with the matching permission.The API user's permissions decide. A tool is listed only when the API user's group has a permission that can use it, and Pro's tools only when the site is licensed. The site checks every call again.
Secrets. The client secret and access tokens never appear in tool results, errors or logs. Keep the file
UMBSOCIAL_ENV_FILEnames out of source control and out of the project folder.Use the site's final address. The token request follows redirects (the SDK's default), and a 307 or 308 redirect sends the form again, client secret included, to the new address. Set
UMBRACO_BASE_URLto the address the site answers on, with no redirect from apex towwwor the like, and don't put a proxy in front that redirects the token path.An assistant with a shell gets round the client-side gates. The off-by-default slices, the confirmations and the tool filters are kept by this server. An assistant that can run commands (Claude Code, for one) can read the client secret from its environment and call the site's API directly. Against such an assistant only the site's own checks hold: give the API user's group no permission you wouldn't give the assistant.
Start on a staging site. Try it against a copy of your site before you connect it to the live one.
Development
npm ci
npm run compile # type-check
npm test # unit tests, against mocks only
npm run build # bundle, then generate the tool types
npm run tools-table # regenerate docs/tools-table.md and docs/refusal-hints.md
UMBSOCIAL_LIVE=1 npm run test:live # against running test sites; see tests/live/README.mdnpm test fails when docs/tools-table.md or docs/refusal-hints.md no longer matches the code. Run npm run tools-table, then copy the tables into the docs site's MCP tools and Error codes pages.
The generated API client is built from a committed Swagger snapshot. See CLAUDE.md for how to regenerate it.
Before bumping a dependency
Every dependency is pinned exactly, and
npm-shrinkwrap.json(published with the package) replacespackage-lock.json. Resolve withnpm install --before=<a date at least two weeks ago>, so nothing newer than two weeks is locked.@umbraco-cms/mcp-dev(CMS_MCP_VERSIONinsrc/config/mcp-servers.ts, which must matchpackage.json): check the environment variables the new version reads against the filter variables blanked for it (INHERITED_FILTERS_BLANKED), so none of this server's own filters reaches it. Check that the eight tools inCMS_TOOLSstill exist under those names, then rerun the live checks.@umbraco-cms/mcp-server-sdk:INTROSPECTION_FLAGSinsrc/index.tsis a copy of the SDK's offline flags (--list-toolsand the rest), which skip the configuration check. Compare it with the new version's.
Releasing
.github/workflows/release.yml builds, tests and publishes to npm with provenance, under the lts-17 dist-tag (beta for a prerelease), when a v* tag matching package.json's version is pushed. It publishes nothing until the owner has chosen how it signs in to npm: npm Trusted Publishing (preferred) or an NPM_TOKEN secret. The workflow's header says how to set up each. Run it by hand for a dry run.
Licence
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Draft, schedule and publish social media posts from your AI assistant.
Make, preview, schedule and publish social posts, carousels, video and reels from your AI assistant.
Draft, schedule, and publish social posts for your workspace straight from your AI.
Draft social posts from your AI assistant; schedules or publishes only after you confirm.
Related MCP Servers
- AlicenseAqualityBmaintenanceOfficial MCP server for PostEverywhere (posteverywhere.ai/social-media-scheduler). Let Claude, ChatGPT, Cursor or any MCP client schedule and publish posts to 13 platforms: Instagram, TikTok, YouTube, LinkedIn, Facebook, X, Threads, Pinterest, Bluesky, Telegram, Discord, WordPress and Google Business Profile. 40 tools: best-time scheduling, threads, cross-posting, campaigns, analytics.33289 npm7MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to draft, schedule, and publish social media content, generate AI text and image variations, analyze performance, and automate social workflows.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to write, preview, publish, schedule, and track posts across X, LinkedIn, Bluesky, Mastodon, Pinterest, TikTok, and YouTube with per-network cost receipts and an explicit user approval step. Also supports voice writing, media uploads, trend finding, and queue management through natural language.MIT
- AlicenseAqualityCmaintenanceEnables AI assistants and autonomous agents to connect to social media accounts and manage, generate, schedule, upload media for, and publish content across Facebook Pages, YouTube, TikTok, Instagram, and X, plus maintain a content pipeline.14MIT