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-server

bulkpublish-mcp

Option 3: From source

git clone https://github.com/azeemkafridi/bulkpublish-api.git

cd bulkpublish-api/mcp-server npm install npm run build node 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:// /mcp?key=bp_…, or publish the https:// /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