postforme-mcp-server
You can manage social media end-to-end through any MCP-compatible AI client using the Post for Me API.
Upload media by requesting signed URLs for images and videos.
Create, schedule, update, delete, and list posts across 10 platforms, with per-platform and per-account overrides.
Fetch post results showing success/failure, errors, and live platform URLs.
Connect, create/upsert, update, list, and disconnect social accounts, including OAuth URL generation.
Retrieve account feeds, including non-Post-for-Me posts, with optional engagement metrics.
Create, list, update, and delete webhooks for post and account events.
Generate visual post previews per account before publishing.
Supports Bluesky, Facebook, Instagram, LinkedIn, Pinterest, Threads, TikTok, TikTok Business, X, and YouTube.
Allows managing social media posts, scheduling, publishing, and retrieving analytics on Bluesky through the Post for Me API.
Allows managing social media posts, scheduling, publishing, and retrieving analytics on Facebook through the Post for Me API.
Allows managing social media posts, scheduling, publishing, and retrieving analytics on Instagram through the Post for Me API.
Allows managing social media posts, scheduling, publishing, and retrieving analytics on Pinterest through the Post for Me API.
Allows managing social media posts, scheduling, publishing, and retrieving analytics on Threads through the Post for Me API.
Allows managing social media posts, scheduling, publishing, and retrieving analytics on TikTok through the Post for Me API.
Allows managing social media posts, scheduling, publishing, and retrieving analytics on YouTube through the Post for Me API.
PostforMe MCP Server
Give any AI agent — Claude, Cursor, Windsurf, or any MCP-compatible client — full control over your social media through natural language.
postforme-mcp-server is free and open source. If it saved you time, sponsoring NerdSnipe Inc pays for the maintenance, bug fixes and new releases that keep it working.
What is this?
This is a Model Context Protocol (MCP) server that connects your AI tools directly to the Post for Me API — a social media scheduling and publishing platform supporting 10 platforms out of the box.
Once installed, your AI can manage social media end-to-end:
"Schedule a post to go out on Instagram, Facebook, and X tomorrow at 9am" "Show me all posts that failed to publish in the last week and tell me why" "Create a YouTube video post with a custom title, tags, and set it to unlisted" "Get the engagement metrics for every post we made this month on TikTok" "Set up a webhook so I'm notified whenever a post goes live"
21 tools covering the full Post for Me API:
Category | Tools |
Media | Upload signed URLs for images and videos |
Social Posts | Create, schedule, update, delete posts across all platforms |
Post Results | Fetch publish outcomes, errors, and platform URLs |
Social Accounts | Connect, manage, and disconnect platform accounts |
Account Feeds | Retrieve every post from a connected account (including non-API posts) with metrics |
Webhooks | Subscribe to post and account events |
Post Previews | Preview exactly what a post will look like before publishing |
Supported platforms: Bluesky · Facebook · Instagram · LinkedIn · Pinterest · Threads · TikTok · TikTok Business · X (Twitter) · YouTube
Related MCP server: social-mic-mcp
Prerequisites
Node.js 18 or later — download here
A Post for Me account — sign up free
A Post for Me API key — takes 30 seconds to get (see below)
How to get your API key
Log in to your Post for Me dashboard
Navigate to Settings → API
Copy your API key
⚠️ Keep your API key secret. Set it in your MCP client config — never commit it to source control.
Installation
No build step needed. Pass your API key in your AI client config and the server runs on demand via npx.
Quick install via package manager
Use npx, pnpm dlx, or bunx to run the server without installing anything globally:
# npm / npx (no install required)
npx @nerdsnipe-inc/postforme-mcp-server
# pnpm
pnpm dlx @nerdsnipe-inc/postforme-mcp-server
# bun
bunx @nerdsnipe-inc/postforme-mcp-serverOr install globally:
npm install -g @nerdsnipe-inc/postforme-mcp-server
# then run:
postforme-mcp-serverConnecting to AI Clients
Claude Desktop
Open (or create) your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"postforme": {
"command": "npx",
"args": ["-y", "@nerdsnipe-inc/postforme-mcp-server"],
"env": {
"POSTFORME_API_KEY": "your_api_key_here"
}
}
}
}Restart Claude Desktop. You should see a hammer icon (🔨) in the chat input — that means MCP tools are active.
Claude Code (CLI)
claude mcp add postforme npx -- -y @nerdsnipe-inc/postforme-mcp-server \
-e POSTFORME_API_KEY=your_api_key_hereOr add it manually to ~/.claude/mcp_servers.json (or your project's .mcp.json):
{
"mcpServers": {
"postforme": {
"command": "npx",
"args": ["-y", "@nerdsnipe-inc/postforme-mcp-server"],
"env": {
"POSTFORME_API_KEY": "your_api_key_here"
}
}
}
}Project-scoped tip: Add a
.mcp.jsonin your project root so everyone on the team picks it up automatically. Add.mcp.jsonto.gitignoreso your API key isn't committed.
Cursor
Open Cursor Settings → MCP (or press
Cmd+Shift+P→ "Open MCP Settings")Click Add Server and fill in:
{
"name": "postforme",
"command": "npx",
"args": ["-y", "@nerdsnipe-inc/postforme-mcp-server"],
"env": {
"POSTFORME_API_KEY": "your_api_key_here"
}
}Save and restart Cursor.
Windsurf
Open ~/.codeium/windsurf/mcp_config.json and add:
{
"mcpServers": {
"postforme": {
"command": "npx",
"args": ["-y", "@nerdsnipe-inc/postforme-mcp-server"],
"env": {
"POSTFORME_API_KEY": "your_api_key_here"
}
}
}
}Any other MCP-compatible client
This server uses stdio transport — the standard for local MCP servers. Your client needs:
Command:
npxArgs:
["-y", "@nerdsnipe-inc/postforme-mcp-server"]Env:
POSTFORME_API_KEY
Refer to your client's MCP documentation for exact config syntax.
All 21 Tools — Full Reference
Media
Use media tools when you need to attach images or videos that aren't already on a public URL. The typical flow is: create upload URL → PUT file to signed URL → use media_url in your post.
Tool | Description |
| Request a signed upload URL for an image or video. Returns |
Social Posts
Posts support three levels of content override — the most specific wins:
Default — top-level
captionandmediaapply to all platformsPlatform —
platform_configurations.instagram,.x,.youtube, etc. override defaults per platformAccount —
account_configurations[].configurationoverrides per specific account
Tool | Description |
| Get a paginated list of social posts. Filter by platform, status ( |
| Create and schedule (or publish immediately) a post across one or more accounts. Omit |
| Get a single post by ID. |
| Replace an existing post's full definition. |
| Delete a post. |
Social Post Results
Post results record the outcome of publishing — whether each platform publish succeeded or failed, plus the live URL.
Tool | Description |
| Get a paginated list of post results. Filter by post ID, platform, or social account ID. |
| Get a single post result by ID. Includes |
Social Accounts
Social accounts are the platform-specific identities used for publishing. Each has a unique id (e.g. spc_xxx) that you reference when creating posts.
Tool | Description |
| Get connected social accounts. Filter by platform, username, external ID, account ID, or status ( |
| Create or upsert a social account using your own OAuth tokens (bring-your-own auth flow). Matches on platform + user_id. |
| Get a single social account by ID. |
| Update a social account's username or external ID. |
| Generate an OAuth URL to connect a user's social platform account. Redirect the user to this URL. Include |
| Disconnect an account — removes all auth tokens and marks it as disconnected. The account record is kept and can be reconnected. |
Social Account Feeds
The account feed returns every post made under a connected account — including posts not made through Post for Me. Requires the account to have been connected with the feeds permission.
Tool | Description |
| Get all posts for a connected account, with optional |
Supported platforms and notes:
Instagram — metrics may take up to 48 hours to appear
Facebook — feeds with
expand=metricsare capped at 10 results by defaultTikTok — consumer API exposes limited analytics; use TikTok Business for full metrics
TikTok Business — full analytics available
YouTube, Threads, X (Twitter), Pinterest — fully supported
Bluesky — views/impressions not available via their API
LinkedIn — metrics only available for company pages
Webhooks
Webhooks let you subscribe to Post for Me events. When an event fires, Post for Me sends a POST to your URL with:
{ "event_type": "social.post.result.created", "data": { ... } }Verify requests using the Post-For-Me-Webhook-Secret header returned when you create a webhook. Failed deliveries are retried with exponential backoff ~8 times over ~1 day.
Tool | Description |
| Get a paginated list of webhooks. Filter by URL, event type, or ID. |
| Create a webhook. Available events: |
| Get a single webhook by ID. |
| Update a webhook's URL and/or subscribed event types. |
| Delete a webhook. |
Social Post Previews
Generate a visual preview of exactly what a post will look like for each account before publishing. No real accounts needed — you can use placeholder IDs for accounts that aren't connected yet.
Tool | Description |
| Preview a post per account. Returns resolved caption, media, platform, and configuration for each specified account. |
Example Prompts
Here are things you can say to your AI once connected:
"Schedule a post to go out tomorrow at 9am on Instagram and Facebook with the caption 'Big announcement coming!' "
"Show me all posts that failed to publish in the last 7 days — include the error reason"
"Get the engagement metrics for every TikTok post we made this month"
"Create a YouTube video post, set the title to 'Q2 Product Demo', make it unlisted, and tag it as made for professionals"
"Post immediately to our X and Threads accounts: 'We just shipped something big. Stay tuned.' "
"What social accounts do we have connected? Show me the platform, username, and connection status"
"Disconnect the Instagram account with ID spc_abc and show me the confirmation"
"Set up a webhook at https://my-site.com/webhooks/postforme that fires whenever a post result comes in"
"Generate a preview of this caption across our Facebook and Instagram accounts before I schedule it"
"Upload this image URL as a media asset and give me the media_url to use in a post"
"Check the status of post sp_xyz — did it publish successfully on all platforms?"
"List all scheduled posts going out this week, sorted by platform"
"Get the full activity feed for our LinkedIn account and show me the top 5 posts by engagement"
"Create a Pinterest post with board ID brd_123 and a link back to our product page"
"Schedule a TikTok post as a draft so I can finish it in the app later"Environment Variables Reference
Variable | Required | Description |
| ✅ Yes | Your Post for Me API key — get it from app.postforme.dev |
That's it — just one variable. Social account IDs, post IDs, and webhook IDs are passed as parameters when you call the relevant tools.
Platform-Specific Configuration Reference
When creating posts, you can pass platform_configurations to override caption, media, or platform-specific settings for each platform:
placement (reels / stories / timeline), collaborators, share_to_feed, location, trial_reel_type (manual / performance), audio_name
placement (reels / stories / timeline), location, collaborators, set_caption_for_each_image
X (Twitter)
poll (duration, options, reply_settings), community_id, quote_tweet_id, reply_settings
YouTube
title, description, tags, category_id, privacy_status (public / private / unlisted), embeddable, license, made_for_kids, contains_synthetic_media, publish_at, recording_date, localizations
TikTok / TikTok Business
privacy_status, allow_comment, allow_duet, allow_stitch, disclose_your_brand, disclose_branded_content, is_ai_generated, is_draft, auto_add_music
title, board_ids, link
Threads
placement (reels / timeline)
LinkedIn, Bluesky
Caption and media overrides only.
Running from source (contributors)
git clone https://github.com/Nerdsnipe-Inc/postforme-mcp-server.git
cd postforme-mcp-server
npm installPoint your MCP client at the source via tsx:
{
"command": "npx",
"args": ["tsx", "/absolute/path/to/postforme-mcp-server/src/index.ts"]
}Or build for production:
npm run build
node dist/index.jsDevelopment
# Install dependencies
npm install
# Run in development mode (no build step needed)
npm run dev
# Type-check without building
npm run typecheck
# Build for production
npm run build
# Watch mode (rebuilds on file changes)
npm run build:watch
# Run tests
npm test
# Run tests with coverage
npm run test:coverageProject Structure
postforme-mcp-server/
├── src/
│ ├── index.ts # MCP server entry point — registers all tools
│ ├── client.ts # HTTP client (auth, URL builder, error handling)
│ └── tools/
│ ├── media.ts # 1 media upload tool
│ ├── social_posts.ts # 5 post CRUD tools
│ ├── social_post_results.ts # 2 post result tools
│ ├── social_accounts.ts # 6 social account tools
│ ├── social_account_feeds.ts # 1 account feed tool
│ ├── webhooks.ts # 5 webhook tools
│ └── social_post_previews.ts # 1 post preview tool
├── tests/
│ ├── helpers.ts # Shared mocks and test utilities
│ ├── client.test.ts # Client and URL builder tests
│ ├── server.test.ts # Tool registry invariant tests
│ └── tools.test.ts # Handler tests for all 21 tools
├── bin/
│ └── postforme-mcp-server.js # CLI entry point (npx / bunx launcher)
├── dist/ # Compiled output (generated by npm run build)
├── .github/
│ └── workflows/publish.yml # npm publish workflow
├── postforme-api-1.yaml # Post for Me OpenAPI spec the tools are built from
├── glama.json # Glama MCP directory listing
├── .env.example # Environment variable template
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── LICENSE
└── README.mdAdding a new tool
Find the relevant module in
src/tools/(or create a new one)Add an entry following the existing pattern:
{
name: "pfm_your_tool_name",
description: "What this tool does and when to use it",
inputSchema: z.object({
id: z.string().describe("The resource ID"),
}),
handler: async (args: Record<string, unknown>, config: PostForMeConfig) => {
const { id } = args as { id: string };
try {
const result = await pfmRequest("GET", `/v1/your-endpoint/${id}`, {
apiKey: config.apiKey,
});
return JSON.stringify(result, null, 2);
} catch (e) {
return formatError(e);
}
},
}Import and spread it into
ALL_TOOLSinsrc/index.tsAdd handler tests in
tests/tools.test.tsRun
npm testto verify everything passesSubmit a PR!
Troubleshooting
The server isn't showing up in my AI client
Make sure Node.js 18+ is installed:
node --versionTry running
npx @nerdsnipe-inc/postforme-mcp-serverdirectly in a terminal to see any errorsRestart your AI client after changing MCP config
Getting "POSTFORME_API_KEY is not set" errors
Verify the
envblock in your MCP client config includesPOSTFORME_API_KEYOr create a
.envfile in your working directory withPOSTFORME_API_KEY=your_key
Getting 401 Unauthorized
Double-check your API key in the Post for Me dashboard
Make sure there are no extra spaces or line breaks in the key
Post published on some platforms but not others
Use
pfm_get_post_resultsfiltered by the post ID to see per-platform outcomesEach result includes an
errorfield explaining what went wrong on that platform
Account feed returns no data / 404
The account must have been connected with the
feedspermissionUse
pfm_create_social_account_auth_urlwithpermissions: ['posts', 'feeds']to reconnect it
Media upload fails
The signed
upload_urlfrompfm_create_media_upload_urlis short-lived — use it immediatelyPUT the file directly to the signed URL, then use the returned
media_urlin your post
Contributing
Pull requests are welcome! Please:
Fork the repo
Create a feature branch (
git checkout -b feature/my-new-tool)Add your changes and write tests (
npm testmust pass)Commit and push, then open a PR
Keep tool names prefixed with pfm_ and handler args typed as Record<string, unknown> with internal casts.
License
MIT © Small Business AI Specialist
Related
Post for Me — the social media scheduling and publishing platform behind the API
GoHighLevel MCP Server — our MCP server for GHL
Support this project
postforme-mcp-server is built and maintained by NerdSnipe Inc, a small independent studio in Ottawa. Social platform APIs break often, and sponsorship funds keeping all 10 working.
Sponsor on GitHub, from $5/month or a one-time amount
Available Tools
21 toolspfm_create_media_upload_urlA
Request a signed upload URL for a media file (image/video). Returns upload_url (PUT your file there) and media_url (use in post). Media assets are temporary: deleted when the post is published, after 24h if unused, or when the post is deleted.
Inputs: no named parameters.
pfm_create_postA
Create and schedule (or publish immediately) a social media post across one or more accounts. Omit scheduled_at to post instantly. Use platform_configurations for per-platform overrides and account_configurations for per-account overrides. The most specific override wins.
Inputs: caption (required), social_accounts (required), media, isDraft, +4 more.
pfm_create_post_previewsA
Generate a preview of what a post will look like for each specified account. You can preview non-connected accounts by specifying a placeholder ID. Returns per-account preview objects with resolved caption, media, platform, and configuration.
Inputs: caption (required), preview_social_accounts (required), media, account_configurations, +1 more.
pfm_create_social_accountA
Create a social account directly (upsert by platform + user_id). If an account with the same platform and user_id already exists, it is updated. Use this when you have OAuth tokens from your own auth flow.
Inputs: user_id (required), platform (required), access_token (required), access_token_expires_at (required), +5 more.
pfm_create_social_account_auth_urlA
Generate an OAuth URL to connect a user's social media account. Redirect the user to this URL; they'll be redirected back after auth. For Quickstart projects using Post for Me system credentials, redirect_url_override is not accepted — configure it in the dashboard instead. Include 'feeds' in permissions to later fetch the account feed and metrics.
Inputs: platform (required), external_id, permissions, platform_data, +1 more.
pfm_create_webhookA
Create a webhook to receive event notifications. Returns a secret in the response — store it to verify incoming requests via the 'Post-For-Me-Webhook-Secret' header. Available events: social.post.created, social.post.updated, social.post.deleted, social.post.result.created, social.account.created, social.account.updated.
Inputs: url (required), event_types (required).
pfm_delete_postB
Delete a social post by its ID.
Inputs: id (required).
pfm_delete_webhookB
Delete a webhook by its ID.
Inputs: id (required).
pfm_disconnect_social_accountA
Disconnect a social account — removes all auth tokens and marks it as disconnected. The account record is kept and can be retrieved and reconnected by the owner.
Inputs: id (required).
pfm_get_account_feedA
Get the social media feed for a connected account — every post made under that account, including posts not created through Post for Me. Pass expand=['metrics'] to include analytics (views, likes, follows, etc.). Requires the account to have been connected with 'feeds' permission. Supported: Instagram, Facebook, TikTok, TikTok Business, YouTube, Threads, X, Bluesky, Pinterest, LinkedIn.
Inputs: social_account_id (required), limit, cursor, expand, +3 more.
pfm_get_postA
Get a single social post by its ID.
Inputs: id (required).
pfm_get_post_resultA
Get a single social post result by its ID. Includes success/failure, errors, platform_data (ID + URL), and media.
Inputs: id (required).
pfm_get_post_resultsA
Get a paginated list of social post results. Filter by post IDs, platform(s), or social account IDs (all use OR logic). Results show success/failure, errors, platform URL, and per-platform data.
Inputs: limit, offset, post_id, platform, +1 more.
pfm_get_postsA
Get a paginated list of social posts. Filter by platform, status, external ID, or social account ID. Multiple filter values use OR logic.
Inputs: limit, offset, status, platform, +2 more.
pfm_get_social_accountA
Get a single social account by its ID.
Inputs: id (required).
pfm_get_social_accountsA
Get a paginated list of connected social accounts. Filter by platform, username, external ID, account ID, or connection status. All filters use OR logic.
Inputs: id, limit, offset, status, +3 more.
pfm_get_webhookA
Get a single webhook by its ID.
Inputs: id (required).
pfm_get_webhooksA
Get a paginated list of webhooks. Filter by URL, event type, or webhook ID.
Inputs: id, url, limit, offset, +1 more.
pfm_update_postA
Update an existing social post (replaces the entire post definition). Use the same schema as create — all fields are re-set.
Inputs: id (required), caption (required), social_accounts (required), media, +5 more.
pfm_update_social_accountC
Update a social account's username or external_id.
Inputs: id (required), username, external_id.
pfm_update_webhookA
Update a webhook's URL and/or subscribed event types.
Inputs: id (required), url, event_types.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool targets a distinct resource and action: posts, post results, social accounts, media uploads, webhooks, and previews are all clearly separated. Even the list/single pairs like pfm_get_posts vs pfm_get_post_results are differentiated by their purpose and filters.
All tool names follow a consistent pfm_<verb>_<object> pattern using snake_case. Verbs are consistently create, get, update, delete, disconnect, and the objects are descriptive, making the API predictable and easy to navigate.
With 21 tools, the count is slightly high but justified by the server's clear scope covering three subdomains: posts, accounts, and webhooks. Each tool has a specific purpose and the count is not inflated with redundant operations.
The surface provides full lifecycle coverage for posts (create, read, update, delete, list, results, previews, media uploads), accounts (create, read, update, disconnect, auth URL, feed), and webhooks (CRUD). The only minor gap is per-post analytics, but pfm_get_account_feed covers metrics when expanded.
Related MCP Connectors
Connect any AI agent to 11+ social platforms: schedule, publish & track posts via hosted MCP.
Lets Claude and AI agents post and schedule on Instagram, TikTok, LinkedIn and 5 more networks.
Schedule and publish social posts across 9 platforms (Instagram, LinkedIn, X, TikTok, Facebook, Threads, Pinterest, Bluesky, Mastodon) straight from Claude, ChatGPT, Cursor, or any MCP client. Create, edit, and reschedule posts, upload media, and pull account and post analytics, follower demographics, and best-time windows. 20 tools, free on every plan.
Post all your social media with your AI agent — 9 networks, from Claude, ChatGPT or Cursor.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceSocial media API and MCP server for AI agents that enables publishing to X, Instagram, LinkedIn, Reddit, Bluesky, and Threads from a single endpoint.13 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables generating, scheduling, and publishing social media posts via Claude or an agent through the MCP protocol.24 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to post, schedule, thread, delete, and analyze social media posts across platforms like X, Bluesky, LinkedIn, and Instagram through a single MCP interface.107 npmMIT
- AlicenseCqualityBmaintenanceEnables posting, scheduling, and analyzing social media content across 16+ platforms through MCP clients like Claude Desktop, Claude Code, and Cursor.55157 npmMIT