ayrshare-unofficial-mcp

v1.0.3

Published

5 months ago

Unofficial MCP server for the Ayrshare social media API. Enables AI agents to publish posts, manage profiles, upload media, handle comments, send messages, view analytics, and configure auto-scheduling.

0High
0Medium
0Low

yardz

mcp ayrshare social-media model-context-protocol ai automation

Ayrshare Unofficial MCP Server

An unofficial MCP (Model Context Protocol) server for the Ayrshare social media API. Enables AI agents to publish posts, manage profiles, upload media, handle comments, send messages, view analytics, and configure auto-scheduling — all through real API calls.

Note: This is an unofficial, community-built project. It is not affiliated with or endorsed by Ayrshare. The official Ayrshare MCP server provides documentation access only — this server actually executes API calls on your behalf.

Prerequisites

Node.js >= 18.0.0
An Ayrshare account with an API key (get one here)
At least a Premium plan for most features (Business plan for profiles and messaging)

Installation

Option 1: npx (Recommended)

Add to your MCP client configuration (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "ayrshare": {
      "command": "npx",
      "args": ["-y", "ayrshare-unofficial-mcp"],
      "env": {
        "AYRSHARE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: Claude Code

claude mcp add ayrshare -e AYRSHARE_API_KEY=your-api-key-here -- npx -y ayrshare-unofficial-mcp

Option 3: Build from Source

git clone https://github.com/yardz/ayrshare-unofficial-mcp.git
cd ayrshare-unofficial-mcp
npm install
npm run build

Then configure your MCP client:

{
  "mcpServers": {
    "ayrshare": {
      "command": "node",
      "args": ["/absolute/path/to/ayrshare-unofficial-mcp/build/index.js"],
      "env": {
        "AYRSHARE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configuration

| Environment Variable | Required | Description | |---|---|---| | AYRSHARE_API_KEY | Yes | Your Ayrshare Primary Profile API key | | AYRSHARE_PROFILE_KEY | No | Default Profile Key for user profile operations (Business plan) |

All tools also accept an optional profileKey parameter to override the default on a per-call basis.

Available Tools (18)

Posts (4 tools)

| Tool | Description | Min Plan | |---|---|---| | create_post | Publish or schedule a post to one or more social platforms | Basic | | get_post | Get details of a specific post by ID | Basic | | get_post_history | List post history with optional filters | Basic | | delete_post | Delete a post or scheduled posts | Basic |

Profiles (3 tools)

| Tool | Description | Min Plan | |---|---|---| | create_profile | Create a new user profile | Business | | list_profiles | List all user profiles | Business | | update_profile | Update a profile's settings | Business |

Media (1 tool)

| Tool | Description | Min Plan | |---|---|---| | upload_media | Upload an image or video to the media library | Premium |

Comments (3 tools)

| Tool | Description | Min Plan | |---|---|---| | post_comment | Post a comment on a social media post | Premium | | get_comments | Get comments on a post | Premium | | delete_comment | Delete a comment | Premium |

Messages (2 tools)

| Tool | Description | Min Plan | |---|---|---| | send_message | Send a direct message (Facebook, Instagram, X) | Business | | get_messages | Get messages and conversations | Business |

Analytics (2 tools)

| Tool | Description | Min Plan | |---|---|---| | get_post_analytics | Get engagement metrics for a post | Premium | | get_social_analytics | Get account-level analytics | Premium |

Auto-Schedule (3 tools)

| Tool | Description | Min Plan | |---|---|---| | set_auto_schedule | Create or update an auto-posting schedule | Premium | | list_auto_schedules | List all configured schedules | Premium | | delete_auto_schedule | Delete a schedule | Premium |

Tool Details

Posts

`create_post`

Publish or schedule a social media post to one or more platforms. Supports text, images, videos, scheduling, and auto-scheduling.

| Parameter | Type | Required | Description | |---|---|---|---| | post | string | Yes | Text content of the post (can be empty if mediaUrls provided) | | platforms | string[] | Yes | Target platforms: bluesky, facebook, gmb, instagram, linkedin, pinterest, reddit, snapchat, telegram, threads, tiktok, twitter, youtube | | mediaUrls | string[] | No | HTTPS URLs of images or videos to attach | | scheduleDate | string | No | ISO 8601 UTC datetime (e.g. 2026-03-01T10:00:00Z) | | shortenLinks | boolean | No | Enable link shortening (requires Max Pack) | | requiresApproval | boolean | No | Put post in approval workflow | | notes | string | No | Internal reference notes | | autoSchedule | object | No | { schedule: true, title?: "schedule-name" } — queue to next slot | | profileKey | string | No | Profile Key override |

Example prompt: "Publish to Instagram and Twitter: 'New product launch! Check it out.' with this image: https://example.com/product.jpg"

`get_post`

Get details of a specific post by its Ayrshare Post ID.

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | Yes | Ayrshare Post ID | | profileKey | string | No | Profile Key override |

Example prompt: "Show me the details of post abc123"

`get_post_history`

List post history with optional filters.

| Parameter | Type | Required | Description | |---|---|---|---| | limit | number | No | Posts to return (default 25, max 1000) | | platforms | string[] | No | Filter by platforms | | status | string | No | Filter: success, error, processing, pending, paused, deleted, awaiting approval | | type | string | No | Filter: immediate or scheduled | | lastDays | number | No | Last N days (default 30, 0 = all) | | profileKey | string | No | Profile Key override |

Example prompt: "Show me my last 10 posts on Instagram"

`delete_post`

Delete a post from social platforms.

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | No* | Ayrshare Post ID to delete | | bulk | string[] | No* | Array of Post IDs for bulk deletion | | deleteAllScheduled | boolean | No* | Delete all pending scheduled posts | | profileKey | string | No | Profile Key override |

*At least one of id, bulk, or deleteAllScheduled is required.

Example prompt: "Delete post abc123"

Profiles

`create_profile`

Create a new user profile for managing separate social media accounts.

| Parameter | Type | Required | Description | |---|---|---|---| | title | string | Yes | Unique profile name | | messagingActive | boolean | No | Enable messaging (default false) | | disableSocial | string[] | No | Social networks to disable | | tags | string[] | No | Tags for organizing |

Example prompt: "Create a profile called 'Client ABC' with Instagram and Twitter enabled"

`list_profiles`

List all user profiles with their linked social accounts.

| Parameter | Type | Required | Description | |---|---|---|---| | title | string | No | Filter by title | | refId | string | No | Filter by reference ID | | hasActiveSocialAccounts | boolean | No | Filter by active accounts | | limit | number | No | Max results (default 5000) | | cursor | string | No | Pagination cursor |

Example prompt: "List all my profiles and their connected social accounts"

`update_profile`

Update an existing profile's settings.

| Parameter | Type | Required | Description | |---|---|---|---| | profileKey | string | Yes | Profile Key to update | | title | string | Yes | New profile title | | disableSocial | string[] | No | Social networks to disable | | messagingActive | boolean | No | Enable/disable messaging | | tags | string[] | No | Tags for organizing |

Example prompt: "Enable messaging on the 'Client ABC' profile"

Media

`upload_media`

Upload an image or video to Ayrshare's media library. Files are stored for 90 days. Max size: 30MB.

| Parameter | Type | Required | Description | |---|---|---|---| | fileUrl | string | No* | Public URL of the file to upload | | base64Data | string | No* | Base64 data URI (e.g. data:image/png;base64,...) | | fileName | string | No | Name for the file | | description | string | No | File description | | profileKey | string | No | Profile Key override |

*One of fileUrl or base64Data is required.

Example prompt: "Upload this image to my media library: https://example.com/photo.jpg"

Comments

`post_comment`

`get_comments`

Get comments on a social media post.

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | Yes | Ayrshare Post ID, Social Post ID, or Social Comment ID | | searchPlatformId | boolean | No | Set true when using Social Post ID | | commentId | boolean | No | Set true when using Social Comment ID | | platform | string | No | Required when searchPlatformId or commentId is true | | profileKey | string | No | Profile Key override |

Example prompt: "Show me the comments on post abc123"

`delete_comment`

Delete a comment from a social media post. Supported on Facebook, Instagram, TikTok, X/Twitter, and YouTube.

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | Yes | Social Comment ID (from get_comments) | | platform | string | Yes | Platform: facebook, instagram, tiktok, twitter, youtube | | profileKey | string | No | Profile Key override |

Example prompt: "Delete the spam comment xyz789 on Instagram"

Messages

`send_message`

Send a direct message on a social platform.

| Parameter | Type | Required | Description | |---|---|---|---| | platform | string | Yes | facebook, instagram, or twitter | | recipientId | string | Yes | Recipient's platform user ID | | message | string | Yes | Message text | | mediaUrls | string[] | No | Media file URLs to attach | | profileKey | string | No | Profile Key override |

Example prompt: "Send a message to user 12345 on Instagram saying 'Thanks for reaching out!'"

`get_messages`

Get messages and conversations from a platform.

| Parameter | Type | Required | Description | |---|---|---|---| | platform | string | Yes | facebook, instagram, or twitter | | status | string | No | active or archived (default: active) | | conversationId | string | No | Get a specific conversation | | conversationsOnly | boolean | No | Return only conversation list (default: false) | | profileKey | string | No | Profile Key override |

Example prompt: "Show me my recent Instagram conversations"

Analytics

`get_post_analytics`

Get engagement analytics for a specific post (likes, views, shares, impressions, comments).

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | Yes | Ayrshare Post ID | | platforms | string[] | No | Filter by platforms (omit for all) | | profileKey | string | No | Profile Key override |

Note: TikTok and YouTube analytics can take 24-48 hours to update.

Example prompt: "What are the engagement metrics for my last post?"

`get_social_analytics`

Get account-level analytics (follower count, demographics, impressions, engagement rates).

| Parameter | Type | Required | Description | |---|---|---|---| | platforms | string[] | Yes | Platforms to get analytics for | | quarters | number | No | Historical range 1-4 quarters (Facebook/Instagram/YouTube) | | daily | boolean | No | Return daily time-series (Facebook/Instagram/TikTok/YouTube) | | profileKey | string | No | Profile Key override |

Example prompt: "Show me my Instagram follower demographics and engagement rate"

Auto-Schedule

`set_auto_schedule`

Create or update an auto-posting schedule with predefined times and days. Posts created with autoSchedule in create_post will be queued to the next available slot.

| Parameter | Type | Required | Description | |---|---|---|---| | schedule | string[] | Yes | Times in UTC (e.g. ["09:00Z", "14:00Z", "18:00Z"]) | | title | string | No | Schedule name (defaults to "default") | | daysOfWeek | number[] | No | 0=Sunday through 6=Saturday (defaults to [0,6]) | | excludeDates | string[] | No | Dates to skip (e.g. ["2026-01-01"]) | | setStartDate | string | No | ISO 8601 UTC datetime to begin scheduling | | profileKey | string | No | Profile Key override |

Example prompt: "Set up auto-scheduling for Monday through Friday at 9am, 2pm, and 6pm UTC"

`list_auto_schedules`

List all configured auto-posting schedules.

| Parameter | Type | Required | Description | |---|---|---|---| | profileKey | string | No | Profile Key override |

Example prompt: "Show me all my auto-posting schedules"

`delete_auto_schedule`

Delete an auto-posting schedule by title.

| Parameter | Type | Required | Description | |---|---|---|---| | title | string | Yes | Schedule title (case-sensitive) | | deleteLastScheduleDate | boolean | No | Also clear the last schedule date | | profileKey | string | No | Profile Key override |

Example prompt: "Delete the 'Weekend Posts' auto-schedule"

Supported Platforms

| Platform | Post | Comment | Message | Analytics | |---|---|---|---|---| | Bluesky | Yes | Yes | - | Yes | | Facebook | Yes | Yes | Yes | Yes | | Google Business | Yes | - | - | Yes | | Instagram | Yes | Yes | Yes | Yes | | LinkedIn | Yes | Yes | - | Yes | | Pinterest | Yes | - | - | Yes | | Reddit | Yes | Yes | - | Yes | | Snapchat | Yes | - | - | Yes | | Telegram | Yes | - | - | - | | Threads | Yes | - | - | Yes | | TikTok | Yes | Yes | - | Yes | | X (Twitter) | Yes | Yes | Yes | Yes | | YouTube | Yes | Yes | - | Yes |

Plan Requirements

| Feature | Basic | Premium | Business | Enterprise | |---|---|---|---|---| | Posts (create, get, history, delete) | Yes | Yes | Yes | Yes | | Media Upload | - | Yes | Yes | Yes | | Comments (post, get, delete) | - | Yes | Yes | Yes | | Analytics (post, social) | - | Yes | Yes | Yes | | Auto-Schedule (set, list, delete) | - | Yes | Yes | Yes | | Profiles (create, list, update) | - | - | Yes | Yes | | Messages (send, get) | - | - | Yes | Yes |

Error Handling

All tools return structured error responses when something goes wrong:

API errors from Ayrshare are returned with the original error code and message
Network errors are caught and returned with a descriptive message
Validation errors (e.g. missing required parameters) are caught before the API call

Error responses have isError: true set so the AI agent can distinguish them from successful responses.

Development

Build

npm install
npm run build

Watch Mode

npm run dev

Test with MCP Inspector

npx @modelcontextprotocol/inspector node build/index.js

Set the AYRSHARE_API_KEY environment variable before running the inspector.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme