BundleSocial MCP
bowlofarugula/bundlesocial-mcp
Gerencia redes sociais via Claude — publica, agenda e analisa em 14+ plataformas
Ver no GitHubServidor MCP remoto rodando em Cloudflare Workers que expõe a API bundle.social para gerenciar conteúdo em 14+ plataformas sociais (X, Instagram, TikTok, LinkedIn, YouTube, Facebook, Pinterest, Reddit, Threads, Bluesky, Mastodon, Discord, Slack, Google Business). Permite postar, agendar, comentar, analisar conteúdo e gerenciar equipes e integrações via TypeScript SDK oficial.
Instalação
npx convez-ai bowlofarugula/bundlesocial-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de publicação multi-plataforma via Claude
- Agendamento centralizado de conteúdo em redes sociais
- Análise e monitoramento de engajamento cross-platform
- Gerenciamento de equipes e integrações de redes sociais
- Integração de workflow de conteúdo com IA
Veredito

Solução profissional para orquestração multi-plataforma social. Suporta múltiplos modos de deploy (single-org com bearer, open, ou BYOK OAuth) adequados a diferentes cenários empresariais. Exige configuração técnica sólida em Cloudflare Workers, mas oferece controle fine-grained de autenticação e escalabilidade.
README
A tradução para o português deste README ainda está na fila.
bundlesocial-mcp
A remote Model Context Protocol server running on
Cloudflare Workers that exposes the bundle.social API as MCP
tools, using bundle.social's official bundlesocial
TypeScript SDK. Post, schedule, comment on and analyze content across 14+ social platforms
(X, Instagram, TikTok, LinkedIn, YouTube, Facebook, Pinterest, Reddit, Threads, Bluesky,
Mastodon, Discord, Slack, Google Business) — plus team & integration management, media
uploads, and post/comment/CSV imports.
It mirrors the surface of bundle.social's local stdio server
(bundlesocial-mcp) as a remote HTTP
server, adapting the local-filesystem bits (uploads, CSV import) to URL-based ingestion
so everything works from a Worker.
Deployment modes
bundle.social has no upstream user OAuth — its API authenticates with a single,
long-lived, org-scoped API key (x-api-key). How you run the server is set entirely by two
secrets: BUNDLESOCIAL_API_KEY (the org key) and the optional PORTAL_BEARER_TOKEN gate.
A — single-org behind a bearer (default)
Set both BUNDLESOCIAL_API_KEY and PORTAL_BEARER_TOKEN. Every /mcp request must carry
Authorization: Bearer <PORTAL_BEARER_TOKEN>, which the Worker verifies (see
src/auth.ts) and otherwise fails closed — so the direct *.workers.dev URL
is not an open bypass. Front it with a gateway that authenticates your users and injects the
bearer server-to-server — e.g. a
Cloudflare MCP server portal
whose Access application (Managed OAuth — DCR, PKCE, RFC 9728, the flow Claude and the MCP
Inspector speak) requires, say, "email ends in @yourcompany.com". End users never paste a key.
This is the default and the simplest secure setup. (You can also connect a client directly by
sending that bearer header yourself — see Connecting directly.)
B — single-org, open or behind your own front
Set BUNDLESOCIAL_API_KEY and leave PORTAL_BEARER_TOKEN unset. The Worker no longer
requires a bearer. Put your own Cloudflare Access / gateway in front to authenticate users,
or run it open if you accept that anyone with the URL can use your org key — authentication is
then your responsibility.
C — per-user "bring your own key" (for multi-customer vendors)
One deployment serving many users, each supplying their own bundle.social API key — so
a vendor can run a single server for all their customers, each acting on their own org. Instead
of a server-side key, the Worker runs an OAuth flow (src/byok-handler.ts):
on connect, each user is shown a small "paste your bundle.social API key" screen
(CSRF-protected), and the key is stored encrypted in their OAuth grant by
@cloudflare/workers-oauth-provider and
read back as this.props.apiKey inside the Durable Object — never logged, never shared between
users. Standard MCP clients (Claude, the MCP Inspector) drive it automatically via Dynamic
Client Registration + PKCE.
Enable it:
npx wrangler kv namespace create OAUTH_KV # the OAuth provider's grant/client store
Then in wrangler.jsonc add the binding + the mode flag, and do not set BUNDLESOCIAL_API_KEY:
"vars": { "BUNDLESOCIAL_PER_USER_KEY": "true" },
"kv_namespaces": [{ "binding": "OAUTH_KV", "id": "<your-oauth-kv-namespace-id>" }]
npm run deploy, then connect a client to /mcp — it'll register, prompt for the key, and go.
(With the flag set but OAUTH_KV unbound, the Worker returns a clear config error.)
As deployed above, /authorize is open — anyone with the URL can connect with their own
key (correct for a public, multi-customer product). If instead you put this Worker behind a
Cloudflare MCP portal (so the portal's Access policy decides who may connect), add the portal
lockdown so the public URL can't bypass that gate and let strangers free-ride on your compute.
Just set PORTAL_HOST (a vars entry) to your portal's hostname (comma-separate several if this
Worker sits behind more than one portal) — it allows the portal's OAuth callbacks and 403s
everything else:
"vars": {
"BUNDLESOCIAL_PER_USER_KEY": "true",
"PORTAL_HOST": "acme.example.com"
}
PORTAL_HOST covers all three portal flows — the Access runtime broker callback, the portal's
/servers-callback (its "Connect" web UI), and the dashboard "Sync capabilities" callback — so
both connecting and the one-time tool-sync work. Leave it unset for the open, standalone case.
(For a non-Cloudflare gateway, list its callback(s) in PORTAL_REDIRECT_URI /
PORTAL_REDIRECT_URI_PREFIXES instead — those are honored too.)
In modes A and B the org key is a Worker secret (BUNDLESOCIAL_API_KEY); rotating it is one
wrangler secret put, no redeploy.
Tools (~60)
Team-scoped tools take a required team (an exact team name or a team id), resolved per
call — there's no implicit active team (see Team context). Errors come back as
{ isError: true } with an actionable message.
| Area | Tools |
|---|---|
| Diagnostics | check_setup (run first), describe_platform |
| Organization & teams | get_organization, get_usage, list_teams, get_team, create_team, update_team, delete_team |
| Integrations (social accounts) | list_integrations, get_integration_by_type, connect_integration, create_integration_portal_link, disconnect_integration, set_integration_channel, unset_integration_channel, refresh_integration_channels, check_integration_connection, refresh_integration_profile, copy_integration, list_integrations_to_delete, list_integration_tools, trigger_integration_tool |
| Posts | create_post, schedule_post, list_posts, get_post, update_post, delete_post, retry_post |
| Comments | create_comment (reply chains), list_comments, get_comment, delete_comment, create_comment_import, list_comment_imports, get_comment_import, list_imported_comments |
| Media | upload_media (from URL), list_media, get_media, delete_media, delete_media_many, init_large_upload, finalize_large_upload |
| Imports | create_post_import, list_post_imports, get_post_import, list_imported_posts, delete_imported_posts, retry_post_import, create_post_csv_import, list_post_csv_imports, get_post_csv_import, get_post_csv_import_status, get_post_csv_import_rows |
| Analytics | get_post_analytics, get_account_analytics, get_bulk_post_analytics, refresh_analytics, get_analytics_summary |
Team context
An API key is org-scoped and almost every endpoint needs a team. Because one key can
span dozens of teams and flows fan out across them, there is deliberately no implicit
"active team" — team-scoped tools take an explicit, required team argument each call.
You can pass either an exact (case-insensitive) team name or a team id; the server
resolves a name to its id (and memoizes the lookup for the session). Use list_teams
(searchable) to discover the name/id to pass.
Posting
create_post / schedule_post mirror the official stdio server's ergonomics:
content— text applied to every targeted platform.platforms— platform names/aliases (x,tiktok,gbp, …) or connected-integration ids. Optional when you passdata(targets are inferred from its keys).media— public URLs, ingested server-side and shared across platforms (this remote server ingests by URL; local paths aren't possible on a Worker).platformSettings— per-platform options, keyed by platform or a flat object applied to all. Use for platform-required fields (Redditsr, PinterestboardName, TikTokprivacy, YouTubemadeForKids, Instagram/Facebooktype).data— advanced escape hatch: the full per-platform map, overrides everything.title— defaults to the first line ofcontent.
create_post publishes now (or draft: true); schedule_post takes a future post_date.
Call describe_platform for each platform's fields. The merge rule (matching the stdio
server): each target gets { text: content, uploadIds: media, ...platformSettings[platform] },
unless data is given, in which case data wins verbatim.
// create_post — shared text + a TikTok-specific required field
{
"team": "My Team",
"content": "We shipped! 🚀",
"platforms": ["x", "tiktok"],
"media": ["https://example.com/clip.mp4"],
"platformSettings": { "tiktok": { "privacy": "PUBLIC_TO_EVERYONE" } }
}
The one deliberate divergence from the stdio server: team is an explicit, required
team (name or id) rather than an optional teamId with an env default — see Team context.
Platform discovery helpers
list_integration_tools / trigger_integration_tool expose read-only lookups the posting
API needs — subreddit flairs/requirements, YouTube categories/playlists/regions, LinkedIn
mentions, Instagram locations/audio, Google Business categories, TikTok trending music.
Architecture
MCP client ──gateway /mcp (no token)──▶ 401 + RFC 9728 metadata (.well-known/oauth-protected-resource)
MCP client ──DCR + PKCE──▶ gateway login (e.g. Cloudflare Access Managed OAuth: SSO / one-time-PIN) + consent
MCP client ──gateway /mcp (bearer)──▶ gateway ──Authorization: Bearer <PORTAL_BEARER_TOKEN>──▶ Worker
Worker (src/auth.ts) checks the bearer, then McpAgent runs bundlesocial SDK calls (key from env)
The diagram above is the multi-user gateway flow; standalone, the MCP client itself sends
Authorization: Bearer <PORTAL_BEARER_TOKEN> straight to the Worker (no portal hop). Either
way, the bundle.social key is an org-scoped Worker secret that doesn't expire — there's no
upstream redirect, token-exchange callback, or refresh to manage. The Worker fails closed:
without the bearer it serves nothing.
Workers notes
nodejs_compatis required. ThebundlesocialSDK has an unconditional top-levelimport crypto from "crypto"(its webhook verifier); the flag resolves it. Otherwise the SDK is purefetch+ WebFormData/Blob, zero runtime deps — no ESM-alias hack needed.- Uploads are URL-based.
upload_mediacallsupload.createFromUrlso bundle.social fetches the asset server-side — no bytes pass through the Worker.create_post_csv_importlikewise fetches the CSV by URL. For raw large bytes,init_large_upload/finalize_large_uploadexpose the signed-PUT primitives.
Deploy
npm install
# Deploy the Worker (its own *.workers.dev URL by default):
npm run deploy
# Set the secrets (never committed):
npx wrangler secret put BUNDLESOCIAL_API_KEY # your bundle.social org API key (bundle.social → org settings)
# Optional — mode A only (omit for mode B); a bearer YOU choose, your gateway/clients must send it:
openssl rand -hex 32 | npx wrangler secret put PORTAL_BEARER_TOKEN
If PORTAL_BEARER_TOKEN is set (mode A), every request must carry it as
Authorization: Bearer <token> or the Worker fails closed; if it's unset (mode B), no
bearer is required. From here, either front the Worker with a gateway that injects the bearer
(see Deployment modes) or connect a client directly
(Connecting directly).
Connecting directly (no gateway)
You don't need a portal. A single operator can point an MCP client straight at the Worker:
- Deploy with
BUNDLESOCIAL_API_KEYset. Either keepPORTAL_BEARER_TOKENset (mode A — your client must present it) or leave it unset (mode B — no bearer; secure the URL yourself). - Connect with an MCP client that can send a static
Authorizationheader — e.g. the MCP Inspector's custom-headers field, or any HTTP MCP client config that supports headers — pointed athttps://<worker>.<subdomain>.workers.dev/mcp. In mode A, addAuthorization: Bearer <your PORTAL_BEARER_TOKEN>. - Smoke-test the bearer gate (mode A) with curl:
BASE=https://<worker>.<subdomain>.workers.dev curl -so /dev/null -w '%{http_code}\n' "$BASE/mcp" # no bearer → 401 (fails closed) curl -so /dev/null -w '%{http_code}\n' "$BASE/mcp" -H "Authorization: Bearer $TOKEN" # with it → past auth
For multiple users, put the Worker behind your own Cloudflare Access / MCP portal that
injects the bearer — see SECURITY.md. To serve many customers who each bring
their own bundle.social key from one deployment, see mode C (planned) above.
Local development
wrangler dev boots the Worker locally; it fails closed without the bearer it expects
(PORTAL_BEARER_TOKEN). Exercise it directly by sending Authorization: Bearer <token>.
See .dev.vars.example for the local secrets.
Connecting a client
- Standalone: point your client at the Worker's
/mcpURL (Streamable HTTP) and configure it to sendAuthorization: Bearer <PORTAL_BEARER_TOKEN>as a static header. - Behind a gateway: point your client at the gateway's
/mcpURL; the client is redirected to the gateway login, signs in, and the gateway forwards requests with the bearer. No key to paste.
MCP Inspector
npx @modelcontextprotocol/inspector@latest
Point it at the /mcp URL; for standalone, add Authorization: Bearer <token> in its
headers field (for a gateway, complete the login). Then run check_setup, then e.g.
list_teams → list_integrations → create_post.
Scripts
| Script | Purpose |
|---|---|
npm run deploy | wrangler deploy. |
npm run dev | wrangler dev. |
npm run typecheck | tsc --noEmit. |
npm run lint / lint:fix | oxlint. |
npm run format / format:check | oxfmt. |
npm run cf-typegen | Regenerate worker-configuration.d.ts after editing the wrangler config. |
Security
See SECURITY.md for how the bundle.social key and the gateway bearer are
handled, rotation/revocation, and how to report a vulnerability.
Support & contributing
Best-effort maintenance — I'll do my best to fix bugs and security issues, and contributions are very welcome. Open an issue or a pull request; help with docs, tests, or features is encouraged. See CONTRIBUTING.md.
Disclaimer
This is an unofficial, community-built integration. It is not affiliated with, endorsed by, or supported by bundle.social. "bundle.social" and the names of the social platforms it connects to are trademarks of their respective owners and are used here only to describe what this tool connects to. Use it in accordance with bundle.social's API terms and each platform's terms of service.
License
Apache-2.0 © 2026 Ian McDonald