@omnisocials/mcp-server

MCP (Model Context Protocol) server for the OmniSocials API. Lets AI assistants manage your social media — create posts, upload media, view analytics, and more.

Prerequisites

• An OmniSocials API key (get one from Settings > API in the app)
• Node.js 18+ (only if using the npm package locally)

Remote MCP URL (no install)

For clients that support remote MCP over HTTP (claude.ai, ChatGPT, Notion, OpenClaw):

https://mcp.omnisocials.com?API_KEY=omsk_live_your_key_here

No installation needed. Paste this URL into your client's MCP settings.

Multiple workspaces

To manage multiple workspaces from a single connection, separate your API keys with commas:

https://mcp.omnisocials.com?API_KEY=omsk_live_key1,omsk_live_key2

Then ask your AI assistant to "list my workspaces" to see all connected workspaces and switch between them. Each key stays scoped to its own workspace for security.

Local Setup (npm package)

Claude Code

claude mcp add omnisocials -- npx -y @omnisocials/mcp-server

Then set your API key (comma-separated for multiple workspaces):

export OMNISOCIALS_API_KEY=omsk_live_your_key_here

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "omnisocials": {
      "command": "npx",
      "args": ["-y", "@omnisocials/mcp-server"],
      "env": {
        "OMNISOCIALS_API_KEY": "omsk_live_your_key_here"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "omnisocials": {
      "command": "npx",
      "args": ["-y", "@omnisocials/mcp-server"],
      "env": {
        "OMNISOCIALS_API_KEY": "omsk_live_your_key_here"
      }
    }
  }
}

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "omnisocials": {
      "command": "npx",
      "args": ["-y", "@omnisocials/mcp-server"],
      "env": {
        "OMNISOCIALS_API_KEY": "omsk_live_your_key_here"
      }
    }
  }
}

Supported Channels

OmniSocials accepts the following channel IDs in create_post, create_and_publish_post, and related tools. Use list_accounts to see which channels a workspace currently has connected.

| Channel ID | Platform | Notes | |------------|----------|-------| | instagram | Instagram | Posts, stories, reels | | facebook | Facebook | Posts, stories, reels | | linkedin | LinkedIn Profile | Personal profile posts | | linkedin_page | LinkedIn Page | Company page posts. Independent from linkedin; a workspace can have both connected at once | | youtube | YouTube | Shorts | | tiktok | TikTok | Posts and reels | | pinterest | Pinterest | Pins (requires board_id) | | x | X (Twitter) | Posts | | threads | Threads | Posts | | bluesky | Bluesky | Posts | | mastodon | Mastodon | Posts |

Available Tools

Posts (7 tools)

| Tool | Description | |------|-------------| | list_posts | List all posts, optionally filter by status | | get_post | Get details of a specific post | | create_post | Create a new post, story, or reel | | create_and_publish_post | Create and publish immediately | | update_post | Update a draft or scheduled post | | delete_post | Delete a post | | publish_post | Publish a draft or scheduled post now | | search_locations | Find an Instagram location to tag (returns place IDs for location_id) |

Media & folders (6 tools)

| Tool | Description | |------|-------------| | list_media | List media files; filter by search (name) or folder_id | | upload_media | Upload media from a URL (max 50MB); set a name and a folder | | update_media | Rename a media file or move it to a folder | | delete_media | Delete a media file | | list_folders | List the workspace's media folders | | create_folder | Create a media folder (optionally nested) |

Accounts (2 tools)

| Tool | Description | |------|-------------| | list_accounts | List connected social media accounts | | get_account | Get account details |

Analytics (3 tools)

| Tool | Description | |------|-------------| | get_post_analytics | Get stats for a published post | | get_analytics_overview | Overview analytics for a time period | | get_account_analytics | Account-level analytics (followers, etc.) |

Workspaces (2 tools)

| Tool | Description | |------|-------------| | list_workspaces | List all workspaces available in this session | | switch_workspace | Switch the active workspace by name (id or list number also accepted) |

Webhooks (5 tools)

| Tool | Description | |------|-------------| | list_webhooks | List all webhooks | | create_webhook | Create a webhook for event notifications | | get_webhook | Get webhook details | | update_webhook | Update a webhook | | delete_webhook | Delete a webhook | | rotate_webhook_secret | Rotate a webhook's signing secret |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OMNISOCIALS_API_KEY | Yes | Your API key (omsk_live_* or omsk_test_*). Comma-separated for multiple workspaces. | | OMNISOCIALS_BASE_URL | No | Custom API base URL (defaults to production) |

Alternative: Agent Skills

For broader AI agent compatibility (works with Cursor, Windsurf, Codex, Gemini CLI, GitHub Copilot, and more), you can also use the OmniSocials Agent Skills package:

npx skills add OmniSocials/omnisocials-agent-skills

The agent-skills package uses a CLI + SKILL.md approach that works in any AI coding tool, not just MCP-compatible ones. See omnisocials-agent-skills on GitHub for details.

API Documentation

Full API docs: docs.omnisocials.com

Changelog

1.5.0

• Added: Attach uploaded media to any tweet in an X thread. x.thread_parts[] now accepts media_ids (the same numeric Library IDs returned by upload_media) on any part, first tweet or reply, alongside the existing media_urls. Combined cap is 4 media per part. This makes graphic-led threads possible without self-hosting image URLs: for example a graphic on the first tweet and the signup link alone in a reply (which keeps the first tweet's reach). Companion server change: media attached to the parent post was previously dropped in thread mode and is now folded into the first tweet.
• Changed: upload_media now shows the uploaded file's public URL in its output, so it can be reused anywhere media_urls is accepted.

1.4.1

• Fixed: Long-form X posts from Premium / Premium+ accounts are no longer wrongly capped at 280 characters. Companion server fix — the API validated X text without checking the account's subscription tier, so single posts over 280 chars were rejected even on Premium. Existing clients benefit automatically once the backend deploys; 1.4.1 only refreshes the tool guidance so agents put Premium long-form (up to 25,000 chars) in content instead of force-splitting it into a thread. Note: X threads still cap each part at 280 chars regardless of tier.

1.3.8

• Fixed: Pinterest pins created via create_post / create_and_publish_post / update_post now publish with title, link, video cover, and alt text. Companion server fix — the API was storing those fields under unprefixed keys while the publisher read them under pinterest_* prefixes, so pins published with no metadata even when the agent passed it. Existing clients on 1.3.7 benefit automatically once the backend deploys.
• Added: pinterest.video_cover and pinterest.alt_text to the tool schemas. alt_text improves accessibility + Pinterest's discoverability for visually impaired users; video_cover sets a custom cover image for video pins (otherwise Pinterest uses a 1s video keyframe).

1.3.7

• Fixed: update_post now accepts per-platform options (youtube, pinterest, instagram, tiktok) — same shape as create_post. Previously these were missing from the update_post schema, so agents that tried to rename a scheduled YouTube Short via youtube.title had the field silently stripped before it reached the server. Renaming a Short, changing privacy, adjusting a Pinterest board, etc. on an existing draft now work.
• Tool descriptions clarify that content is the post caption / body, and for YouTube Shorts becomes the video description — not the Short's title. To rename a Short, use youtube.title.

1.3.6

• Metadata-only republish of 1.3.5 to refresh the README on npmjs.com. No code changes from 1.3.5.

1.3.5

• Fixed: YouTube Shorts title, tags, privacy_status, category_id, made_for_kids, notify_subscribers, and contains_synthetic_media now actually take effect when publishing through MCP/API. Previously the publisher silently ignored these and every Short went live as "YouTube Short" with default privacy. Companion server fix — clients on 1.3.4 also benefit once the backend deploys; 1.3.5 only refreshes the tool descriptions.
• Tool descriptions clarify that the youtube options block only applies when type is "reel" and youtube is among the selected channels, and that title falls back to "YouTube Short" when omitted.

1.3.4

• Prevent accidental publishing. Tool descriptions now front-load the difference: create_post is explicitly the draft path, create_and_publish_post carries a STOP gate listing every phrasing ("draft", "schedule", "review first", "save it", etc.) that should make the agent fall back to create_post. Default is "create draft" whenever there's ambiguity.
• Draft + publish responses now include an Open in OmniSocials link. Drafts and scheduled posts link to the editor (/create-post/:id) so the user can review or edit before it goes live. Published posts link to the details view (/posts/:id). Applies to create_post, create_and_publish_post, update_post, and get_post.

1.3.2 / 1.3.3

• Fixed: create_post and create_and_publish_post no longer throw str.replace is not a function when the API returns per-platform content as an object. Response formatters now wrapped in a safe fallback so a formatting throw can never surface as a tool error (closes the duplicate-on-retry trap).
• Fixed: list_posts and get_post now render the correct Channels and Scheduled values. Previously read the wrong field names (p.channels / p.scheduled_at) and fell through to created_at for the date.
• Fixed: Date rendering always includes an explicit UTC suffix. Agents convert to local time when answering the user.
• Fixed: list_media now labels video files as Video (was showing Image for every .mp4).

(1.3.3 is a metadata republish of 1.3.2 to refresh the README on npmjs.com. No code changes between 1.3.2 and 1.3.3.)

License

MIT