PostPulse

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

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

1. Install dependencies and build:

npm install

npm run build

1. 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 explains the options. For a larger file:

1. If it has a public URL, pass it in mediaUrl.
2. Otherwise call create_upload_link, and after the user has uploaded it, get_upload_link for its key.

create_upload_link

Get a link that lets the user upload files from their device to their PostPulse media library in a browser, with no login. Use it for a file without a public URL, including a file attached to the chat, which does not reach this server. The tool does not wait for the upload: once the user says they are done, call get_upload_link.

Parameters: none.

Returns: the link, when it expires, the steps for the user, 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.
• 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 uploaded 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:

• Show the user the file names and ask them to confirm before scheduling, because whoever has the link can add files. Then pass the keys of CONFIRMED files to schedule_post.
• A PENDING file may still be finishing: check again after the user says it is uploaded. A REJECTED file cannot be used.
• An empty list means the user has not finished: ask them, do not poll.

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