PostMCP MCP Server
OfficialConnect AI assistants to PostMCP AI to manage, schedule, and publish social media posts across LinkedIn, X, Facebook, Instagram, Threads, Bluesky, and YouTube Shorts.
Retrieve authenticated user details: plan, credit balance, AI token count (
get_user_info).List connected social media accounts and their profile usernames (
get_connected_accounts).List scheduled, published, and failed posts (
list_posts).Create and schedule or immediately publish posts with content, media, target platforms/accounts, date/time (
create_post).Publish an existing scheduled post immediately (
publish_post_now).Update an existing post's content, platforms, schedule, or status (
update_post).Delete or cancel a scheduled or failed post (
delete_post).Additional README capabilities: preflight checks, reschedule/retry/reset stuck posts, per-post/profile analytics, media uploads/import, image generation, carousels/galleries, batching up to 20 calls, multi-workspace, OAuth/API key auth, Stdio/HTTP transport.
Allows AI assistants to create, schedule, and publish social media posts to Bluesky.
Allows AI assistants to create, schedule, and publish social media posts to Facebook.
Allows AI assistants to create, schedule, and publish social media posts to Instagram.
Allows AI assistants to create, schedule, and publish social media posts to Threads.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PostMCP MCP Server Schedule a post on LinkedIn and Twitter for tomorrow at 10am"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PostMCP AI Model Context Protocol (MCP) Server
Official PostMCP AI Model Context Protocol (MCP) Server. Connect your social media publishing pipelines directly into AI assistants, desktop applications, IDE workflows, and web environments like Claude Desktop, Claude.ai, Cursor, and ChatGPT Custom GPTs.
Supported platforms include LinkedIn, X (Twitter), Facebook, Instagram, Threads, Bluesky, and YouTube Shorts.
š Features & Capabilities
š¤ 20 Built-in Tools: Workspaces, connected accounts and their token health, the post queue, pre-flight checks, create/schedule/reschedule/publish/retry/delete, per-post and per-profile analytics, media uploads, image generation, and batching.
š¼ļø Carousels & galleries: Pass
mediaUrlsto publish a carousel on Instagram and Threads, a multi-photo post on Facebook and LinkedIn, or a four-image gallery on X and Bluesky - one call, every network's ceiling checked up front.ā” Dual Transport Modes: Native Stdio mode (for local desktop apps & IDEs) and Streamable HTTP mode (for web services, Claude.ai, and remote connectors).
š Flexible Authentication: Auto-detects API key from environment variables (
POSTMCPAI_API_KEY), URL query parameters (?apikey=YOUR_KEY), or HTTP authorization headers (x-api-key,Bearer token).šļø Multi-Workspace Aware: The API key carries its own workspace, so a bare key is enough. To act on another one, every tool takes an optional
workspaceId, also settable per connection (?projectId=...,x-project-id) or per process (POSTMCPAI_PROJECT_ID).š¤ ChatGPT Actions Compatible: Includes built-in OpenAPI 3.0 specification generator (
/openapi.json) and REST endpoints (/api/tools/:name) for ChatGPT Custom GPT integration.š OAuth with PKCE and RFC 9728: Per-user consent, persistent encrypted grants, rotating tokens and DCR for ChatGPT/Codex. Requires the production settings in OAUTH.md; API-key clients remain supported.
š§© Installable plugin: Account onboarding, publishing, scheduling and analytics workflows. See PLUGIN.md and run
npm run package:plugin.
Related MCP server: YaparAI Enterprise MCP Server
š Repository Architecture
mcp-server/
āāā bin/
ā āāā cli.js # Executable CLI entry point (Stdio / HTTP mode runner)
āāā src/
ā āāā config.js # Centralized configuration & environment loader
ā āāā client.js # Backend API client, API key & workspace extraction
ā āāā platforms.js # Platform limits, credit pricing & post cost helper
ā āāā tools/
ā ā āāā definitions.js# MCP tool JSON schemas & parameter specifications
ā ā āāā handlers.js # MCP tool execution handlers
ā ā āāā index.js # Tool definitions aggregator
ā āāā server.js # MCP Server instance factory
ā āāā routes/
ā ā āāā oauth.js # OAuth 2.0 & RFC 9728 discovery endpoints
ā ā āāā openapi.js # OpenAPI 3.0 schema & ChatGPT REST endpoints
ā ā āāā mcpHttp.js # MCP Streamable HTTP transport (/mcp)
ā ā āāā health.js # Health check & system metadata endpoints
ā āāā app.js # Express application factory
ā āāā index.js # Main library entry point
āāā index.js # Executable wrapper script
āāā package.json
āāā README.mdāļø Environment Configuration
Environment Variable | Description | Default Value |
| Required. Your secret API key from the PostMCP AI dashboard. |
|
| Backend API root. Only set for a self-hosted or local backend. |
|
| Optional. Overrides the workspace the API key is bound to. Overridden in turn by a call's | The workspace the API key was issued from |
| Setting this launches the server in Remote Streamable HTTP Mode. |
|
š ļø MCP Tools Reference
Every tool below also accepts an optional workspaceId (from list_workspaces) to act on a specific workspace.
Reading
Tool Name | Description | Required | Optional |
| Authenticated user: plan, credit balance, active workspace and role. | ā |
|
| Every workspace the user belongs to, with ids, roles, and connected platforms. | ā | ā |
| Connected social profiles with the | ā |
|
| Connections whose token expired or is close to it and need reconnecting. | ā |
|
| A connected profile's followers, following, post count and views from its network. Stored reading is free; |
|
|
| Post queue, newest first, with per-profile delivery status, pagination and counts. | ā |
|
| One post in full: which profiles received it, live URLs, and per-profile errors. |
| ā |
| Views, likes, comments, shares, saves and clicks per profile, plus the raw platform metrics. Stored reading is free; |
|
|
Writing
Tool Name | Description | Required | Optional |
| Dry run: character limits, unconnected profiles, missing media, carousel ceilings, credit cost. Publishes nothing. |
|
|
| Draft, schedule, or immediately publish a post to named profiles. Each profile becomes its own post with its own id. Several |
|
|
| Publish an existing post immediately; also retries a failed post, skipping delivered profiles. |
| ā |
| Update content, target profiles, schedule, media, or status. |
|
|
| Move a post to a new slot, keeping copy and targets. Re-arms failed and draft posts. |
|
|
| Release a post stuck mid-publish so it can be retried. Delivered profiles keep their state. |
|
|
| Cancel and delete a scheduled or failed post. |
| ā |
| Generate a post image and return its hosted URL for |
|
|
| Authorize a direct image/video upload; returns a signed PUT URL and the future public URL. |
|
|
| Register a successfully uploaded file in the media library and return |
|
|
| Copy a public image/video into storage and the media library; returns |
|
|
Media uploads
For a local file, the MCP client needs an HTTP upload capability:
Call
create_media_upload_urlwithfileName,contentType(MIME type), andfileSize(bytes). For example:{ "fileName": "launch.png", "contentType": "image/png", "fileSize": 245760 }.PUT the raw file bytes to the returned
uploadUrlwith the returnedheaders. Do not send your PostMCP API key to storage. The URL expires afterexpiresInseconds (normally 900); request another if it expires. The file is not uploaded merely by creating the URL.After the PUT succeeds, call
complete_media_uploadwith the returnedpublicUrlasurl, the returnedkey, and the same file metadata. Use the sameworkspaceIdon both tools. This registers the file; it does not transfer or verify the bytes.Use the returned
mediaUrlincreate_postorupdate_post, or collect several URLs inmediaUrlsfor a carousel.
For an existing public file, call import_media_from_url with { "url": "https://example.com/launch.png" }. The backend downloads it and returns the stored mediaUrl in one call. The URL must serve the file directly without authentication; private-network URLs are rejected by the backend.
Storage supports PNG, JPEG, GIF, WebP, AVIF, HEIC, MP4, MOV, WebM and M4V, with a 25 MiB image ceiling and a 512 MiB video ceiling. Individual social platforms have stricter publishing requirements; use preflight_post before publishing. File bytes and base64 never travel through the MCP JSON request. If library registration fails after storage succeeds, the result includes librarySaved: false and a warning while preserving the usable mediaUrl.
Batching
Tool Name | Description | Required | Optional |
| Run up to 20 of the tools above in one request, in order. Tool names are validated before anything executes, so a typo cannot leave half a batch written. Cannot nest. |
|
|
{
"calls": [
{ "id": "img", "tool": "generate_image", "arguments": { "prompt": "launch banner" } },
{
"tool": "create_post",
"arguments": {
"content": "We shipped it š",
"targetAccounts": [
{ "platform": "linkedin", "profileId": "lin_7741903" },
{ "platform": "twitter", "profileId": "tw_1293847", "content": "We shipped it š" }
],
"scheduleDate": "2026-09-01",
"scheduleTime": "10:00",
"timezone": "Asia/Kolkata"
}
}
],
"stopOnError": true
}The reply carries one entry per call ā { id, tool, ok, result } or { id, tool, ok: false, error } ā plus counts and, when a failure stopped the batch, the calls that were skipped.
Carousels
mediaUrls is the ordered attachment set. One URL is an ordinary media post; two or more publish as a multi-media post on every network but YouTube, with the first URL as the cover:
Platform | Items per post | Video in a set of several? | Lands as |
2ā10 | yes | Carousel | |
Threads | 2ā20 | yes | Carousel |
up to 10 | no | Multi-photo post | |
up to 20 | no | Multi-image post | |
X / Twitter | up to 4 | no | Gallery on one tweet |
Bluesky | up to 4 | no | Gallery on one post |
YouTube | 1 | ā | One video per upload |
{
"content": "Five things we learned shipping v2 š",
"targetAccounts": [
{ "platform": "instagram", "profileId": "17841400000000" },
{ "platform": "threads", "profileId": "9988776655" },
{ "platform": "twitter", "profileId": "tw_1293847",
"mediaUrls": ["https://cdn.example.com/v2/1.png", "https://cdn.example.com/v2/2.png", "https://cdn.example.com/v2/3.png", "https://cdn.example.com/v2/4.png"] }
],
"mediaUrls": [
"https://cdn.example.com/v2/1.png",
"https://cdn.example.com/v2/2.png",
"https://cdn.example.com/v2/3.png",
"https://cdn.example.com/v2/4.png",
"https://cdn.example.com/v2/5.png"
],
"scheduleDate": "2026-09-01",
"scheduleTime": "10:00",
"timezone": "Asia/Kolkata"
}Only Instagram and Threads mix video into a carousel; everywhere else a set of several must be images only, and a video goes out on its own.
create_postrefuses a set a target will not take before any credits are spent, naming the profile and the rule.preflight_postwith the samemediaUrlsreports the same thing plus amediaSetLimitsmap, so check first when one carousel goes to several networks.A profile can carry its own
mediaUrlson itstargetAccountsentry (or invariantsas{ "twitter": { "mediaUrls": [...] } }), replacing the shared set - the way to give X and Bluesky a four-slide cut of a longer carousel.Every slide is copied into PostMCP's own storage at write time, like a single attachment, so a host that expires the links later does not break the scheduled post. One slide failing at publish time fails that profile's post rather than publishing a shorter carousel;
publish_post_nowretries it.update_postwithmediaUrlsreplaces the whole set (add, remove or reorder slides); an empty array removes all media. Every post returned bylist_posts/get_postcarriesmediaUrlsalongsidemediaUrl.
Notes for clients
Target profiles, not platforms.
targetAccountssends only to the profiles named;platformsfans out to every connected profile on each platform.One post per profile.
create_poststores a separate post per targeted profile, so each can be edited, retried or cancelled on its own. Give per-profile copy throughtargetAccounts[].contentor thevariantsmap.Always pass
timezonewhen a wall-clock time matters. The backend defaults to UTC, so a 9:00 IST post scheduled without a zone goes out at 14:30 IST.Credits are charged per profile delivered to (X/Twitter costs 5, others 1), plus a one-off 50-credit surcharge when the copy contains a link.
preflight_postreports this before you commit.Analytics are read on request, never in the background.
list_postsandget_connected_accountscarry what the last reading stored, free.get_post_analytics(one post, every network it went to) andget_profile_analytics(one connected profile: followers, posts, views) withrefresh: trueread the network now for 1 credit each; without it, the stored reading is free.engagementsis likes + comments + shares on every network, so it compares across platforms. Anullmeans the network does not report that metric (Bluesky has no views), anerrornaming reconnect means the account predates the insights permission and its owner must reconnect it, andunavailable: truemeans the network never answers for that kind of post (LinkedIn personal profiles).
š» Client Integration Guides
1. Claude Desktop App (Stdio Mode)
Add the configuration below to your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"postmcpai": {
"command": "npx",
"args": ["-y", "@postmcpai/server"],
"env": {
"POSTMCPAI_API_KEY": "pmcp_sec_your_secret_api_key_here"
}
}
}
}2. Cursor IDE
Open Cursor Settings -> Features -> MCP.
Click + Add New MCP Server.
Fill in the details:
Name:
postmcpaiType:
commandCommand:
npx -y @postmcpai/server
Under Environment Variables, add:
POSTMCPAI_API_KEY=pmcp_sec_your_secret_api_key_here
Click Save.
3. Claude.ai & Remote Web Connectors (Streamable HTTP / SSE Mode)
Host this server on any cloud service (Render, Railway, Fly.io, Vercel) or tunnel your local machine using ngrok.
Launching in HTTP Mode:
export PORT=3000
# Each remote caller supplies its own API key or OAuth token.
npm run start:sseConnecting to Claude.ai:
Provide your public MCP URL with your API key attached:
https://your-hosted-domain.com/mcp?apikey=pmcp_sec_your_secret_api_key_hereClaude.ai will discover tool capabilities via
/mcpand authenticate seamlessly.That URL is all you need: the key is bound to the workspace it was issued from, so tools act on that workspace without being told. To point the same key at a different workspace, append
&projectId=YOUR_WORKSPACE_ID(or send anx-project-idheader); individual tool calls can still override either withworkspaceId.
4. ChatGPT Custom GPTs (REST Actions)
When configuring a Custom GPT Action, specify your server URL (e.g.
https://your-hosted-domain.com).Import the OpenAPI schema directly from:
https://your-hosted-domain.com/openapi.jsonSet Authentication to API Key (Bearer
Authorizationor customx-api-key). This is a GPT Actions integration, not a per-customer OAuth plugin. For the plugin, use OAUTH.md.
5. Programmatic Node.js Library Usage
You can also use @postmcpai/server as a library in your own Node.js backends:
import { createServer, createExpressApp, makeBackendRequest } from "@postmcpai/server";
// Create a standalone MCP Server instance
const mcpServer = createServer(() => process.env.POSTMCPAI_API_KEY);
// Or create an Express app with all remote routes attached
const app = createExpressApp();
app.listen(3000);š§Ŗ Local Testing & Development
# Clone the repository
git clone https://github.com/postmcp/postmcp-mcp-server.git
cd postmcp-mcp-server
# Install dependencies
npm install
# Start in Stdio Mode
npm start
# Start in HTTP Mode with hot reload
npm run devš License
Distributed under the MIT License. Copyright Ā© 2026 PostMCP AI.
Available Tools
7 toolscreate_postC
Schedule or publish immediately a post to one or more social media platforms or specific accounts.
Inputs: content (required), mediaUrl, platforms, scheduleDate, +3 more.
delete_postA
Cancel and delete a scheduled or failed post from the database.
Inputs: id (required).
get_connected_accountsA
List all active, connected social media channels and their associated profile usernames.
Inputs: no named parameters.
get_user_infoA
Retrieve details of the logged-in user including subscription plan, credit balance, and AI token count.
Inputs: no named parameters.
list_postsA
Retrieve a list of scheduled, published, and failed social media posts.
Inputs: no named parameters.
publish_post_nowA
Broadcast an existing scheduled post immediately to its platforms.
Inputs: id (required).
update_postB
Update the fields (content, platforms, schedule date/time) of an existing post.
Inputs: id (required), status, content, platforms, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 7 tools
Each tool targets a distinct resource or action: user info, connected accounts, and post management (list, create, publish, update, delete). The actions are clearly separated, and even create_post vs publish_post_now are distinguished by whether the post is new or existing.
All tool names follow a consistent verb_noun pattern in snake_case (get_user_info, list_posts, create_post, publish_post_now, delete_post, update_post). The naming is uniform and predictable.
Seven tools is well-scoped for a social media post management server. Each tool covers a necessary operation without redundancy or bloat, making the set easy to navigate.
The tool set provides full CRUD for posts (create, list, update, delete), plus a specialized publish action, and includes user/account context. This covers the core workflow of managing social media posts from scheduling to publication.
Maintenance
Related MCP Connectors
Draft, schedule and publish social media posts from your AI assistant.
Schedule, draft and publish social media posts on 18 platforms from your AI assistant.
Plan, schedule and publish social media posts to 13 platforms from any AI assistant.
Draft, schedule and publish social posts to nine platforms from any AI agent.
Related MCP Servers
- AlicenseAqualityBmaintenanceOfficial MCP server for PostEverywhere (posteverywhere.ai/social-media-scheduler). Let Claude, ChatGPT, Cursor or any MCP client schedule and publish posts to 13 platforms: Instagram, TikTok, YouTube, LinkedIn, Facebook, X, Threads, Pinterest, Bluesky, Telegram, Discord, WordPress and Google Business Profile. 40 tools: best-time scheduling, threads, cross-posting, campaigns, analytics.33289 npm7MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to manage social media accounts and CRM operations, including posting, analytics, inbox management, and customer management.22Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to draft, schedule, and publish social media content, generate AI text and image variations, analyze performance, and automate social workflows.MIT
- AlicenseAqualityCmaintenanceEnables AI assistants and autonomous agents to connect to social media accounts and manage, generate, schedule, upload media for, and publish content across Facebook Pages, YouTube, TikTok, Instagram, and X, plus maintain a content pipeline.14MIT