postmcp/postmcp-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
---
⚙️ Environment Configuration
| Environment Variable | Description | Default Value |
| :--- | :--- | :--- |
| POSTMCPAI_API_KEY | **Required.** Your secret API key from the PostMCP AI dashboard. | None |
| POSTMCPAI_API_URL | Backend API root. Only set for a self-hosted or local backend. | https://api.postmcpai.com |
| POSTMCPAI_PROJECT_ID | Optional. Overrides the workspace the API key is bound to. Overridden in turn by a call's workspaceId. | The workspace the API key was issued from |
| PORT | Setting this launches the server in **Remote Streamable HTTP Mode**. | None (Defaults to Stdio 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 |
| :--- | :--- | :--- | :--- |
| get_user_info | Authenticated user: plan, credit balance, active workspace and role. | — | workspaceId |
| list_workspaces | Every workspace the user belongs to, with ids, roles, and connected platforms. | — | — |
| get_connected_accounts | Connected social profiles with the profileId needed to target them. | — | workspaceId |
| get_account_health | Connections whose token expired or is close to it and need reconnecting. | — | workspaceId |
| get_profile_analytics | A connected profile's followers, following, post count and views from its network. Stored reading is free; refresh reads the network now for 1 credit. | platform, profileId | refresh |
| list_posts | Post queue, newest first, with per-profile delivery status, pagination and counts. | — | status, page, limit, all |
| get_post | One post in full: which profiles received it, live URLs, and per-profile errors. | id | — |
| get_post_analytics | Views, likes, comments, shares, saves and clicks per profile, plus the raw platform metrics. Stored reading is free; refresh reads the networks now for 1 credit. | id | refresh |