PostPulse MCP Server

An MCP (Model Context Protocol) server that connects AI assistants to PostPulse — a social media management platform. Schedule posts, upload media, and manage accounts across Instagram, Facebook, YouTube, TikTok, Threads, LinkedIn, Pinterest, X (Twitter), Bluesky, and Telegram — all through natural language.

Features

• Multi-platform posting — Schedule posts to 10 social media platforms from a single interface

• Media management — Find files in the media library, import images and videos by URL, give the user a link to upload files from their device, or upload small files as base64

• Account management — List and manage all connected social media accounts

• Read your posts — List posts by date range and get each post's per-platform status, public link, error and metrics

• Delete posts and media — Permanently delete a post or one account's publication of it, optionally on the social network too, and files from the media library

• Connect social accounts from the chat — Get a secure link to connect or reconnect an account without opening the PostPulse app

• OAuth 2.0 authentication — Secure access via Auth0-based token verification

• Streamable HTTP transport — Modern MCP transport protocol for reliable communication

Related MCP server: SocialCrawl

Supported Platforms

Quick Start

Hosted Server (Recommended)

PostPulse runs a hosted MCP server at https://mcp.post-pulse.com — no setup required. Point your MCP client to this URL and authenticate via OAuth.

Example MCP client configuration:

{
  "mcpServers": {
    "postpulse": {
      "url": "https://mcp.post-pulse.com"
    }
  }
}

Install via Smithery

You can also install through Smithery:

npx -y @smithery/cli install post-pulse/mcp-server --client claude

Self-Hosted

If you prefer to run the server yourself:

1. Clone the repository:

git clone https://github.com/PostPulse/mcp-server-postpulse.git
cd mcp-server-postpulse

2. Install dependencies and build:

npm install
npm run build

3. Start the server:

npm start

Or with Docker:

docker build -t mcp-server-postpulse .
docker run -p 3000:3000 mcp-server-postpulse

Environment Variables

Tools

list_accounts

List all connected social media accounts with their IDs, platforms, usernames, and display names. Use this as the first step to discover available accounts before scheduling posts or accessing chats.

Parameters: None

Returns: JSON array of account objects (id, platform, username, name, needsReauthorization). A new user has no accounts yet: the result is [] plus a hint to use connect_account. Accounts with needsReauthorization: true must be reconnected with connect_account before posting; the result names them in a second text block.

connect_account

Get a secure PostPulse link that connects (or reconnects) a social media account to PostPulse directly from the chat. The user opens the link in any browser and lands on a PostPulse page that shows which PostPulse account (masked email) the social account will be attached to. After Continue and approving access on the platform, the page says "Account connected — return to your chat". The tool does not wait for completion: once the user says they are done, call list_accounts to confirm the account.

Parameters:

Behaviour:

• For a new connection the tool first checks that the user may add an account (plan or credits). If not, it returns the reason and a link to billing.

• The link is single-use, tied to the user's PostPulse account and valid for 24 hours; the platform consent starts only when the user clicks Continue on the page. It must not be shared: whoever completes it attaches their social account to this PostPulse account.

• If too many links are requested in a short time, the tool asks to wait a few minutes and try again.

• Telegram cannot be connected with a link: the tool returns instructions to connect it on https://post-pulse.com/app/accounts instead.

• A new Facebook connection creates one FACEBOOK_PAGE account per picked Page: post to it directly, without list_chats. For TELEGRAM and for a reconnected FACEBOOK account, call list_chats afterwards to pick the channel or Page.

• Clients that support URL-mode elicitation additionally get a native "open this link" dialog; the link is always in the text result as well.

• Errors that happen in the browser (account limit, account already used by another PostPulse user, expired link) are shown on the page, not returned by the tool.

list_chats

List publishing destinations for accounts that have sub-destinations. Facebook accounts publish to Pages, Telegram accounts publish to channels or chats, and Pinterest accounts publish to boards. Call this before scheduling posts to these platforms — use the returned id as the facebookPageId, telegramChannelId or pinterestBoardId in schedule_post.

Only supports accounts whose platform is FACEBOOK, TELEGRAM or PINTEREST. Other platforms, including FACEBOOK_PAGE (an account that is one Page), do not have sub-destinations and should be posted to directly.

Parameters:

Returns: JSON array of destination objects (id, title, type, platform).

upload_media

Upload a media file for use in scheduled posts. Supports two modes: importing from a public URL (with automatic processing) or uploading a small file directly as base64. Returns a media key to reference in schedule_post.

Parameters:

One of mediaUrl, both mediaData and mediaType, or importId must be provided.

Long imports: a call waits about 50 seconds. An import that takes longer keeps running on the server, and the call returns its id and state instead of a media key. Call upload_media again with importId to keep waiting; do not start the import again.

File size: a request to this server is limited to 100 KB, and base64 data travels inside the request, so mediaData fits only files up to about 75 KB. A larger request gets a 413 with a JSON-RPC error that lists the ways to get a media key.

Ways to get a media key, whichever the agent can use. An agent that can reach the files adds them itself, and the user has nothing to upload by hand.

• list_media: a file already in the library.

• The gallery at https://post-pulse.com/app/gallery: a person, or an agent with a browser where the user is logged in, adds files there, then list_media gives their keys.

• create_upload_link: a link to a plain HTTPS page with no login, where a person or an agent with a browser can add files. The result also gives the steps for an agent with only HTTP access. get_upload_link then gives the keys of those files.

• upload_media with mediaUrl: a file at a public URL.

• upload_media with mediaData: a file up to about 75 KB.

create_upload_link

Get a link to a plain HTTPS page with no login, where a person or an agent with a browser can add files to the user's PostPulse media library. The result also gives the steps for an agent with only HTTP access. An agent that can reach the files adds them itself. An agent that cannot, for example with a file attached to a chat, which does not reach this server, gives the user the link. The tool does not wait for the upload: get_upload_link lists the files that have arrived.

Parameters: none.

Returns: the link, when it expires, the steps for a person opening it, the steps for an agent over HTTP (presign, PUT, confirm), and the uploadLinkId for get_upload_link.

Behaviour:

• The link takes several files until it expires. The page shows whose PostPulse library the files go to.

• A person who is to add the files needs the link in full, including the part after #.

• It must not be shared: whoever has the link can add files to this PostPulse library. For this reason the tool never writes the link to a log.

• If too many links are requested, the tool asks to wait and try again.

get_upload_link

List the files added through a link from create_upload_link. Use it instead of list_media to get exactly these files, without knowing their names.

Parameters:

Returns: a JSON object with expiresAt and files (key, filename, contentType, sizeBytes, status), followed by what to do next.

Behaviour:

• Pass the keys of CONFIRMED files to schedule_post. If someone else added the files, first show them the file names and ask them to confirm, because whoever has the link can add files. Files the agent added itself need no confirmation.

• A PENDING file may still be finishing: check again when its upload has ended. A file added over HTTP stays PENDING until its confirm call. A REJECTED file cannot be used.

• An empty list means nothing has arrived yet.

list_media

List the files in the media library, newest first. Use it to find a file already in the library, such as one uploaded on the PostPulse website at https://post-pulse.com/app/gallery, by its name and pass its key to schedule_post. A file uploaded with mediaData appears a few minutes later, but its key from upload_media works at once.

Parameters:

Returns: a JSON object with items (key, filename, contentType, sizeBytes), page, size, totalItems and totalPages. An empty library also gets a hint with the gallery link.

schedule_post

Schedule a social media post to one or more connected accounts. Supports platform-specific options like publication type (feed, reel, story), video titles, and topic tags. Posts are scheduled for a future time using ISO-8601 timestamps.

Parameters:

list_posts

List posts scheduled or published in a date range (by scheduled time), oldest first: id, overall status, scheduled time, platforms and text. The API is not paginated, so one call spans at most 93 days; split longer periods into several calls. Drafts without a scheduled time are not listed.

Parameters:

get_post

Get one post with its outcome on each account: publicationId (for delete_post), platform, status, public link to the published post (url), platform post id, error message, text, attached media (key for delete_media, file name and type) and the latest metrics PostPulse has:

• impressions, engagements, likes, shares, comments and profileClicks, common to all platforms. A metric the platform does not report is null;

• lastUpdatedTime;

• platformAnalytics: the platform's own analytics for the post under the platform's field names, e.g. view_count on TikTok or views and quotes on Threads. Its fields depend on the platform and the post type, so do not expect a fixed set. It is null when the platform reports none.

Metrics of published posts are refreshed from the platform on each call.

Parameters:

delete_post

Permanently delete a post from PostPulse with its results and metrics, in any status. This cannot be undone, so the tool is marked destructive and its description tells the agent to get the user's confirmation first. Media files stay in the library (see delete_media).

Parameters:

Refusals (nothing is deleted in PostPulse):

• post_in_progress: the post is being published or, for one publication, its media is still being imported. Try again when that finishes.

• platform_deletion_not_supported: deleteFromPlatform is strict, and these platforms cannot delete the post. No platform was called.

• platform_deletion_failed: a platform call failed. Posts already removed from other platforms stay removed, and retrying is safe.

Which platforms support deleteFromPlatform is listed in the API documentation.

delete_media

Permanently delete a file from the media library and storage. A post that is not published yet is deleted on the accounts where it is left without the media the platform requires or without any content; a published or failed post stays and only loses the attachment. What is already published stays on the social network. If a post using the file is being published, the tool returns post_in_progress and nothing is deleted.

Parameters:

Resources

postpulse://accounts

An MCP resource providing the list of all connected social media accounts. Returns the same data as the list_accounts tool in JSON format, including needsReauthorization.

Authentication

This server uses OAuth 2.0 with Auth0. OAuth metadata is discoverable at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.

No existing PostPulse account is needed: signing in through the MCP client (with Google or a passwordless email code) creates the PostPulse account on first use. The user then connects social accounts with connect_account.

Dynamic Client Registration (DCR)

MCP clients that support OAuth can register automatically via Dynamic Client Registration (RFC 7591). The server advertises a registration_endpoint in its OAuth metadata, so compliant clients (such as Claude Desktop, Cursor, etc.) will handle the entire OAuth flow — registration, authorization, and token exchange — without any manual setup from the user.

Pre-Registered Client Credentials

If you already have client credentials created through the PostPulse Developer Portal, you can configure your MCP client to use them directly instead of DCR. Pass your client_id and client_secret in the OAuth authorization code flow against the PostPulse authorization server.

HTTP Endpoints

Every response carries X-Robots-Tag: noindex, nofollow so search engines never index this host.

Example Workflow

A typical interaction with the PostPulse MCP server:

1. List accounts to find connected social media profiles

2. Connect an account (if the platform is missing) with connect_account

3. Get a media key (optional): find a file with list_media, import one by URL with upload_media, or add files through a link from create_upload_link

4. Schedule a post with content, media, and a future publish time

User: "Schedule an Instagram reel for tomorrow at 9am with the video at https://example.com/video.mp4 and caption 'Check this out!'"

A video without a public URL

A video is too large for mediaData, so it goes through an upload page, with no login. An agent that can reach the file and the page adds it itself, and has nothing to confirm. In a plain chat the user does it:

User:      "Post my new reel to Instagram tomorrow at 9:00 UTC. The file is on my computer."
Assistant: create_upload_link → link, uploadLinkId
           "Open this link, add the video, and tell me when the page says it is uploaded."
User:      "Done"
Assistant: get_upload_link(uploadLinkId) → { files: [{ key: "<user>/<id>.mp4", filename: "reel-42.mp4", status: "CONFIRMED", ... }], ... }
           "I got reel-42.mp4. Is this the right file?"
User:      "Yes"
Assistant: schedule_post(accountId: 123, platform: INSTAGRAM, mediaPaths: ["<user>/<id>.mp4"], publicationType: REELS, scheduledTime: ...)

First run (new user)

User:      "Post 'Hello LinkedIn!' to my LinkedIn tomorrow at 10:00 UTC"
Assistant: list_accounts → [] ("No social accounts are connected yet")
           connect_account(platform: LINKEDIN) → link
           "Open this link, check the PostPulse account on the page, approve access on LinkedIn, then tell me when you are done."
User:      "Done"
Assistant: list_accounts → [{ id: 123, platform: LINKEDIN, ... }]
           schedule_post(accountId: 123, platform: LINKEDIN, content: "Hello LinkedIn!", scheduledTime: ...)