# BulkPublish MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) 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)

```bash
npx @bulkpublish/mcp-server
```

### Option 2: Global install

```bash
npm install -g @bulkpublish/mcp-server
bulkpublish-mcp
```

### Option 3: From source

```bash
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:

```bash
export BULKPUBLISH_API_KEY=bp_your_api_key_here
```

Get your API key at [app.bulkpublish.com/developer](https://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`

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

If you installed from source:

```json
{
  "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:

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

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

```bash
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`):

| Endpoint | Purpose |
|----------|---------|
| `POST /mcp` | MCP Streamable HTTP (stateless) |
| `GET /.well-known/mcp/server-card.json` | Static metadata so registries can skip scanning |
| `GET /health` | Liveness check |

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:

```bash
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.

### Tool profiles

The server ships three tool profiles, chosen with `BULKPUBLISH_TOOL_PROFILE`:

| Profile | Tools | Default for |
|---|---|---|
| `core` | 20 — channels, posts, media, analytics, and the interactive panels | The hosted HTTP server (`dist/http.js`), which is what the Claude and ChatGPT directories list |
| `inbox` | 27 — everything in `core`, plus the Inbox and comment tools: `list_conversations`, `get_conversation`, `reply_to_conversation`, `update_conversation`, `list_post_comments`, `reply_to_comment`, `moderate_comment` | Opt-in on a hosted deployment (`BULKPUBLISH_TOOL_PROFILE=inbox`). The `core` tools in it are identical to the `core` profile's |
| `full` | Every tool (including the Inbox and comment tools; labels, hashtag groups, templates, calendar notes, review links, client-connect links, recurring schedules, channel sets, RSS feeds, chunked uploads, quota) | The local stdio server (`npx @bulkpublish/mcp-server`) |

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](#tool-profiles)); tools marked ✉ are in `inbox` (with every ★ tool); the rest need `full`.

| Tool | Description |
|------|-------------|
| **Posts** | |
| `create_post` ★ | Create and optionally schedule a post (supports reels, stories, carousels, threads via `postTypeOverrides`) |
| `compose_post` ★ | Open an interactive composer UI (MCP Apps) to draft/schedule a post; submits via `create_post` |
| `update_post` ★ | Update a draft or scheduled post |
| `get_post` ★ | Get a single post with full details |
| `list_posts` ★ | List posts with filters (status, search, date range) |
| `delete_post` ★ | Delete a post |
| `publish_post` ★ | Publish a draft post immediately |
| `retry_post` ★ | Retry a failed post |
| `approve_post` | Approve a post awaiting team approval (roles with post:approve) |
| `reject_post` | Reject a pending post back to draft, with an optional reason |
| `get_post_metrics` ★ | Get engagement metrics (impressions, likes, comments, shares). Each platform entry carries `supportedMetrics` — a key not in that list is a stored `0`, not a measurement |
| `publish_story` | Publish as a story to Facebook or Instagram |
| `bulk_posts` | Bulk delete or retry multiple posts |
| `get_queue_slot` ★ | Get the next optimal time slot for a channel |
| **Channels** | |
| `list_channels` ★ | List all connected social media channels |
| `get_channel_health` | Check channel token health |
| `get_channel_options` | Get platform-specific options (boards, playlists) |
| `search_mentions` | Search users for @mention (X, Bluesky, Mastodon, LinkedIn Pages — LinkedIn results carry the `vanityName` slug they matched on) |
| **Channel Sets** | |
| `list_channel_sets` | List saved channel groups for one-click multi-channel targeting |
| `create_channel_set` | Save a named group of channels (max 50 per org, names unique per org) |
| `update_channel_set` | Rename a set or change its channels |
| `delete_channel_set` | Delete a channel set |
| **RSS Autopost** | |
| `list_rss_feeds` | List RSS/Atom feeds polled every 15 minutes (new items become posts) |
| `create_rss_feed` | Add a feed (max 20 per org); `mode` = `draft` (default, items become drafts) or `publish` (auto-published); optional `fieldMapping` controls how items render (caption template, media pick, truncation, per-channel overrides) |
| `update_rss_feed` | Change, pause, or re-point a feed (changing `feedUrl` re-baselines it — the backlog is not flooded) |
| `delete_rss_feed` | Stop and remove a feed |
| **Media** | |
| `upload_media` ★ | Upload a media file from a URL (or local path on the stdio server) |
| `get_media` | Get a media file by ID |
| `list_media` ★ | List uploaded media files |
| `delete_media` | Delete a media file |
| `create_media_upload` ★ | Reserve a presigned R2 URL for a direct browser upload (used by the composer) |
| `finalize_media_upload` ★ | Record an uploaded object as a media file after the browser PUT (used by the composer) |
| `create_multipart_upload` | Start a chunked upload for large media (videos up to 1GB) — presigned URLs for fixed 10MB parts |
| `complete_multipart_upload` | Assemble the uploaded parts (partNumber + ETag each) and record the media file |
| `abort_multipart_upload` | Cancel an in-progress chunked upload and free its stored parts |
| **Labels** | |
| `create_label` | Create a new label |
| `list_labels` | List all labels |
| `update_label` | Update a label name or color |
| `delete_label` | Delete a label |
| **Analytics** | |
| `get_analytics` ★ | Get analytics summary for a date range |
| **Schedules** | |
| `list_schedules` | List recurring schedules |
| `create_schedule` | Create a recurring schedule |
| `update_schedule` | Update a schedule |
| `delete_schedule` | Delete a schedule |
| **Inbox and comments** | |
| `list_conversations` ✉ | List direct messages, reviews and comment threads, newest activity first, with filters and paging (Pro and Business plans) |
| `get_conversation` ✉ | Read one conversation's messages, oldest first; does not mark it read |
| `reply_to_conversation` ✉ | Send a reply to the person on the platform right away; it cannot be unsent |
| `update_conversation` ✉ | Mark read or unread, archive or reopen, snooze, or assign a conversation; nothing is sent |
| `list_post_comments` ✉ | List the comments and reactions on a published post, per channel, with the ids the reply and moderate tools take |
| `reply_to_comment` ✉ | Post a public reply to a comment right away, as the channel the post went out on |
| `moderate_comment` ✉ | Like, unlike, hide, unhide or delete a comment on the platform (delete is permanent) |
| **Account** | |
| `get_quota_usage` | Check current account usage (hidden when `BULKPUBLISH_HIDE_BILLING=1`) |
| **Interactive UI (MCP Apps)** | |
| `compose_post` ★ | Open the interactive post composer (also listed above) |
| `view_analytics` ★ | Open an interactive analytics dashboard |
| `view_posts` ★ | Open an interactive posts list |
| `view_channels` ★ | Open an interactive channels view |
| `view_media` ★ | Open an interactive media gallery |
| `view_quota` | Open an interactive account-usage view (hidden when `BULKPUBLISH_HIDE_BILLING=1`) |

## Interactive UI (MCP Apps)

In hosts that support [MCP Apps](https://blog.modelcontextprotocol.io/posts/2025-11-21-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.

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

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `BULKPUBLISH_API_KEY` | Yes | — | Your API key (starts with `bp_`) |
| `BULKPUBLISH_BASE_URL` | No | `https://app.bulkpublish.com` | API base URL (for self-hosted instances) |
| `BULKPUBLISH_TOOL_PROFILE` | No | `full` (stdio) / `core` (hosted HTTP) | `core`, `inbox` or `full` — see [Tool profiles](#tool-profiles) |
| `BULKPUBLISH_HIDE_BILLING` | No | — | `1` drops `get_quota_usage` and `view_quota` (only relevant with `full`; `core` never includes them) |

## License

MIT