convez.ai
MCP ServerIntegração & APIsAvançado
bowlofarugula

BundleSocial MCP

bowlofarugula/bundlesocial-mcp

Gerencia redes sociais via Claude — publica, agenda e analisa em 14+ plataformas

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.

AreaTools
Diagnosticscheck_setup (run first), describe_platform
Organization & teamsget_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
Postscreate_post, schedule_post, list_posts, get_post, update_post, delete_post, retry_post
Commentscreate_comment (reply chains), list_comments, get_comment, delete_comment, create_comment_import, list_comment_imports, get_comment_import, list_imported_comments
Mediaupload_media (from URL), list_media, get_media, delete_media, delete_media_many, init_large_upload, finalize_large_upload
Importscreate_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
Analyticsget_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 pass data (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 (Reddit sr, Pinterest boardName, TikTok privacy, YouTube madeForKids, Instagram/Facebook type).
  • data — advanced escape hatch: the full per-platform map, overrides everything.
  • title — defaults to the first line of content.

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_compat is required. The bundlesocial SDK has an unconditional top-level import crypto from "crypto" (its webhook verifier); the flag resolves it. Otherwise the SDK is pure fetch + Web FormData/Blob, zero runtime deps — no ESM-alias hack needed.
  • Uploads are URL-based. upload_media calls upload.createFromUrl so bundle.social fetches the asset server-side — no bytes pass through the Worker. create_post_csv_import likewise fetches the CSV by URL. For raw large bytes, init_large_upload / finalize_large_upload expose 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:

  1. Deploy with BUNDLESOCIAL_API_KEY set. Either keep PORTAL_BEARER_TOKEN set (mode A — your client must present it) or leave it unset (mode B — no bearer; secure the URL yourself).
  2. Connect with an MCP client that can send a static Authorization header — e.g. the MCP Inspector's custom-headers field, or any HTTP MCP client config that supports headers — pointed at https://<worker>.<subdomain>.workers.dev/mcp. In mode A, add Authorization: Bearer <your PORTAL_BEARER_TOKEN>.
  3. 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 /mcp URL (Streamable HTTP) and configure it to send Authorization: Bearer <PORTAL_BEARER_TOKEN> as a static header.
  • Behind a gateway: point your client at the gateway's /mcp URL; 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

ScriptPurpose
npm run deploywrangler deploy.
npm run devwrangler dev.
npm run typechecktsc --noEmit.
npm run lint / lint:fixoxlint.
npm run format / format:checkoxfmt.
npm run cf-typegenRegenerate 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

Ver o original no GitHub

Bom para

Relacionados