Postmcp MCP Server

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 mediaUrls to 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.

📁 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

🛠️ MCP Tools Reference

Every tool below also accepts an optional workspaceId (from list_workspaces) to act on a specific workspace.

Reading

Writing

Media uploads

For a local file, the MCP client needs an HTTP upload capability:

1. Call create_media_upload_url with fileName, contentType (MIME type), and fileSize (bytes). For example: { "fileName": "launch.png", "contentType": "image/png", "fileSize": 245760 }.
2. PUT the raw file bytes to the returned uploadUrl with the returned headers. Do not send your PostMCP API key to storage. The URL expires after expiresIn seconds (normally 900); request another if it expires. The file is not uploaded merely by creating the URL.
3. After the PUT succeeds, call complete_media_upload with the returned publicUrl as url, the returned key, and the same file metadata. Use the same workspaceId on both tools. This registers the file; it does not transfer or verify the bytes.
4. Use the returned mediaUrl in create_post or update_post, or collect several URLs in mediaUrls for 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

{

"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:

{

"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