# Ayrshare Unofficial MCP Server
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
An unofficial MCP (Model Context Protocol) server for the [Ayrshare](https://www.ayrshare.com) 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](https://www.ayrshare.com))
- 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`):
```json
{
"mcpServers": {
"ayrshare": {
"command": "npx",
"args": ["-y", "ayrshare-unofficial-mcp"],
"env": {
"AYRSHARE_API_KEY": "your-api-key-here"
}
}
}
}
```
### Option 2: Claude Code
```bash
claude mcp add ayrshare -e AYRSHARE_API_KEY=your-api-key-here -- npx -y ayrshare-unofficial-mcp
```
### Option 3: Build from Source
```bash
git clone https://github.com/yardz/ayrshare-unofficial-mcp.git
cd ayrshare-unofficial-mcp
npm install
npm run build
```
Then configure your MCP client:
```json
{
"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`
Post a comment on a social media post.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | Yes | Ayrshare Post ID or Social Post ID |
| `comment` | string | Yes | Comment text |
| `platforms` | string[] | Yes | Target platforms: `bluesky`, `facebook`, `instagram`, `linkedin`, `reddit`, `tiktok`, `twitter`, `youtube` |
| `searchPlatformId` | boolean | No | Set true when using Social Post ID |
| `mediaUrls` | string[] | No | Image URLs to attach |
| `profileKey` | string | No | Profile Key override |
**Example prompt:** *"Comment 'Thanks for the feedback!' on my last Instagram post"*
#### `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
```bash
npm install
npm run build
```
### Watch Mode
```bash
npm run dev
```
### Test with MCP Inspector
```bash
npx @modelcontextprotocol/inspector node build/index.js
```
Set the `AYRSHARE_API_KEY` environment variable before running the inspector.
## License
MIT
