npm package: @omnisocials/mcp-server
Description: MCP server for OmniSocials API - manage social media posts, media, accounts, analytics, and webhooks
Latest version: 1.2.0

# @omnisocials/mcp-server

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

## Prerequisites

- Node.js 18+
- An OmniSocials API key (get one from **Settings > API** in the app)

## Setup

### Claude Code

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

Then set your API key:

```bash
export OMNISOCIALS_API_KEY=omsk_live_your_key_here
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

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

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

```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 |

### Media (3 tools)

| Tool | Description |
|------|-------------|
| `list_media` | List all media files |
| `upload_media` | Upload media from a URL (max 50MB) |
| `delete_media` | Delete a media file |

### 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.) |

### 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_*`) |
| `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:

```bash
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](https://github.com/OmniSocials/omnisocials-agent-skills) for details.

## API Documentation

Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)

## License

MIT