BulkPublish

BulkPublish MCP Server

A Model Context Protocol server that lets Claude and other AI assistants interact with the BulkPublish social media publishing API.

What it does

This MCP server exposes BulkPublish API operations as tools that AI assistants can call directly. You can ask Claude to schedule posts, check analytics, upload media, manage labels, and more — all through natural conversation.

Installation

Option 1: npx (recommended)

npx @bulkpublish/mcp-server

Option 2: Global install

npm install -g @bulkpublish/mcp-serverbulkpublish-mcp

Option 3: From source

git clone https://github.com/azeemkafridi/bulkpublish-api.gitcd bulkpublish-api/mcp-servernpm installnpm run buildnode dist/index.js

Requires Node ≥ 20.19. npm run build bundles the composer UI with Vite (build:ui), then compiles the server with tsc.

Configuration

Set your API key as an environment variable:

export BULKPUBLISH_API_KEY=bp_your_api_key_here

Get your API key at app.bulkpublish.com/developer.

Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{  "mcpServers": {    "bulkpublish": {      "command": "npx",      "args": ["-y", "@bulkpublish/mcp-server"],      "env": {        "BULKPUBLISH_API_KEY": "bp_your_api_key_here"      }    }  }}

If you installed from source:

{  "mcpServers": {    "bulkpublish": {      "command": "node",      "args": ["/absolute/path/to/bulkpublish-api/mcp-server/dist/index.js"],      "env": {        "BULKPUBLISH_API_KEY": "bp_your_api_key_here"      }    }  }}

Claude Code

Add the MCP server to your Claude Code configuration:

claude mcp add bulkpublish -- npx -y @bulkpublish/mcp-server

Set the environment variable in your shell profile or .env file:

export BULKPUBLISH_API_KEY=bp_your_api_key_here

Remote / hosted server (HTTP)

The npx/stdio setup above runs the server locally. Web clients that cannot spawn a local process — claude.ai custom connectors and Smithery's gateway — connect to a hosted HTTP endpoint instead. Alongside the stdio bin, the server ships a Streamable HTTP transport (dist/http.js, run with npm run start:http):

It is multi-tenant — the process holds no API key. Each caller supplies their own bp_… key per request via the connection URL (?key=bp_…), a Smithery ?config= blob, or an Authorization: Bearer bp_… / X-BulkPublish-Key header. initialize, tools/list, and resources/* need no key (so scans and tool discovery work); a tools/call without one returns 401.

A Dockerfile is included:

docker build -t bulkpublish-mcp . && docker run -p 8080:8080 bulkpublish-mcp

Once deployed, add it to claude.ai → Settings → Connectors → Add custom connector as https://<host>/mcp?key=bp_…, or publish the https://<host>/mcp URL to Smithery.

Auto-connect for organizations

The hosted server at https://mcp.bulkpublish.com/mcp supports enterprise-managed authorization (the MCP io.modelcontextprotocol/enterprise-managed-authorization extension). An organization on Claude Team or Enterprise can connect every member to BulkPublish at once, with no sign-in screen and no pasted API key: the workspace owner trusts the organization's issuer (its Claude organization, or its identity provider) under API → MCP Auto-connect in BulkPublish, and members are matched to the workspace by their verified email address. In Claude, an organization Owner sets it up under Organization settings → Connectors → Set up auto-connect.

For client developers: the token endpoint accepts grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer with an identity assertion, from a public client identified by a Client ID Metadata Document (an https client_id). Access tokens from this grant last up to an hour and carry no refresh token. Dynamic client registration and the authorization-code flow are unchanged.

Tool profiles

The server ships three tool profiles, chosen with BULKPUBLISH_TOOL_PROFILE:

Set BULKPUBLISH_TOOL_PROFILE=full on a hosted deployment to expose everything, or core locally to keep a small tool list. The panels' buttons call back into create_post, publish_post, retry_post, update_post, delete_post, list_channels, list_media, get_post, create_media_upload and finalize_media_upload, so all of those are in core.

Every tool carries a title and explicit readOnlyHint, destructiveHint, idempotentHint and openWorldHint booleans; npm run check:annotations verifies that for every profile (add --table to print the per-tool justification table used in directory submissions).

Available Tools

Tools marked ★ are in the core profile (see Tool profiles); tools marked ✉ are in inbox (with every ★ tool); the rest need full.

Interactive UI (MCP Apps)

In hosts that support MCP Apps — Claude, ChatGPT, VS Code, Goose, Postman, and the Smithery playground — the compose_post tool opens an interactive composer rendered inline in the conversation: pick channels, write content, optionally schedule, then submit. On submit it calls create_post through the host bridge, so the sandboxed iframe never holds your API key. Hosts without MCP Apps support simply receive a plain-text summary, so nothing breaks.

Several tools render UIs — compose_post (composer), view_analytics, view_posts, view_channels, view_media, and view_quota. Each is a self-contained widget under src/ui/<name>/, bundled into a single HTML file with Vite (one single-input pass per widget — see scripts/build-ui.mjs) and inlined into the server via src/ui/widgets.generated.ts. They share the BulkPublish web app's design tokens (src/ui/tokens.css), so the look matches. A View receives its data from the triggering tool's structuredContent and can call other tools back through the host bridge — so the sandboxed iframe never holds your API key. Hosts without MCP Apps support simply receive a plain-text summary.

Prompts

The server also lists ready-made prompts: starting points your MCP client shows in its prompt or slash menu (for example /schedule_post or /weekly_report). Each one tells the assistant which tools to call, the limits that apply, and to ask before anything is published, sent or deleted.

A prompt is listed only when every tool it needs is available, so what you see depends on the tool profile: all means every profile, including the hosted core server; inbox, full needs the inbox or full profile; full needs the full profile (the npm server's default). plan_usage is also left out when BULKPUBLISH_HIDE_BILLING=1. Prompts read nothing from your account until the assistant follows them.

Example Conversation

Here is an example of using the BulkPublish tools in Claude:

You: Schedule a post for tomorrow at 9am EST saying "Excited to announce our new feature! Check it out at example.com" to all my connected channels.

Claude: Let me check your connected channels first.

[Calls list_channels]

You have 3 active channels:

• X/Twitter: @yourcompany (ID: 1)
• LinkedIn: Your Company Page (ID: 2)
• Instagram: @yourcompany (ID: 3)

Now I'll schedule the post for tomorrow at 9:00 AM Eastern.

[Calls create_post with content, channels, scheduledAt: "2025-01-16T14:00:00Z", timezone: "America/New_York", status: "scheduled"]

Done! Your post has been scheduled:

• Post ID: 42
• Status: scheduled
• Scheduled for: January 16, 2025 at 9:00 AM EST
• Channels: X/Twitter, LinkedIn, Instagram

You: How did my posts perform this month?

Claude: [Calls get_analytics with from: "2025-01-01", to: "2025-01-31"]

Here is your January analytics summary:

• Total posts: 28
• Published: 25
• Failed: 1
• Scheduled (pending): 2
• By platform: X/Twitter (25 posts, 24 published), LinkedIn (20 posts, 19 published), Instagram (15 posts, all published)
• Best day: January 12 with 5 posts

You: Upload this image and create a draft post with it: https://example.com/product-launch.png

Claude: [Calls upload_media with url]

Image uploaded successfully (ID: 15, 1200x630px, 245KB).

[Calls create_post with content and mediaFileIds]

Draft post created (ID: 43) with the product launch image attached. You can review and publish it when ready.

Environment Variables

License

MIT