Ayrshare MCP server

Get real-time analytics for a post identified by its NATIVE Social Post ID (the platform's own ID, not an Ayrshare Post ID). Notes: exactly one platform required; body is locked to {id, platforms:[platform], searchPlatformId:true} — no extra keys forwarded. For posts created through Ayrshare where you have the Ayrshare Post ID, use get_post_analytics instead. Requires a valid API key (same authentication as every other tool).

Account-level analytics and demographics for a linked social network account (follower count, impressions, views, demographics). Notes: quarters 1-4 activates date filtering; daily and period60Days are incompatible; Facebook needs >=100 page likes for full analytics; Instagram demographics need >=100 engagements in 30 days; LinkedIn/TikTok may lag 24-48 h. userId/userName (X/Twitter) look up a specific user and must use the account API key only, with no profileKey. This is NOT analytics about an Ayrshare User Profile — for profiles use list_profiles. Requires a valid API key (same authentication as every other tool).

Read comments for a post using an Ayrshare Post ID, Social Post ID, or Social Comment ID. Notes: `platform` is required when `searchPlatformId` or `commentId` is true. Comment data refreshes every 10 minutes; X/Twitter uses exponential backoff. Facebook and Instagram return up to the most recent 1,000 comments.

Add a top-level comment to a published post using an Ayrshare Post ID or Social Post ID. Notes: When `searchPlatformId` is true, `platforms` must contain exactly one entry. `mediaUrls` supports one image URL on Facebook, LinkedIn, and X/Twitter only. Comments on an X Thread land on the first Tweet.

Reply to a comment using an Ayrshare Comment ID or Social Comment ID. Notes: When `searchPlatformId` is true, `platforms` must contain exactly one entry. `commentUrn` is required for LinkedIn Social Comment ID replies. `videoId` is required for TikTok Social Comment ID replies. `mediaUrls` supports one image URL on Facebook and LinkedIn only. Reddit is not supported for comment replies.

Fetch direct messages or conversations for one messaging platform (facebook, instagram, whatsapp, twitter). Notes: responses are cached for 60 s, or 15 s on X/Twitter. Use conversationsOnly to list thread summaries, conversationId to scope to one thread, and limit + next for pagination. Every platform returns a bounded page of at most 100 messages or conversations with a meta.pagination cursor; follow next while hasMore is true.

Send a direct message on facebook, instagram, or twitter. Notes: At least one of message or mediaUrls is required. At least one of recipientId or conversationId is required. Facebook and Instagram require recipientId and only accept messages within the platform's messaging window.

Return the account's current direct-message auto-response settings (account-level, not platform-scoped). Notes: Takes no parameters. Returns autoResponseActive, autoResponseMessage, and autoResponseWaitSeconds when configured. To update settings use set_auto_response.

Configure the account's direct-message auto-response (account-level, not platform-scoped). Notes: At least one of autoResponseActive, autoResponseMessage, or autoResponseWaitSeconds is required. Do NOT send autoResponseMessage as "": it does not reset the message. Sent alone the API returns code 101, and sent with another field it is silently ignored. Send the default text explicitly instead. To read the current settings use get_auto_response.

List the User Profiles under the caller's Primary Profile (which is not itself included); all inputs are optional filters/pagination. Notes: Profile Keys are NOT returned for security — retrieve them from the dashboard. Requires a valid API key (same authentication as every other tool).

Create a new User Profile under the caller's Primary Profile. Required: `title` (unique, shown on the social-account-linking page). Returns `profileKey` and `refId` — SENSITIVE values that must be securely stored (profileKey is only returned at creation time or via the dashboard). Notes: To invite a team member set `team: true` and supply `email`. Use `disableSocial` to block specific networks for this profile. Requires a valid API key (same authentication as every other tool).

Generate a single sign-on (JWT) SOCIAL-ACCOUNT LINKING URL for one User Profile (sub-profile), so a client/customer can connect their own social networks (Facebook, Instagram, X, LinkedIn, TikTok, etc.) to that profile. This is the onboarding step after `create_profile`: it returns a hosted linking page URL you hand to the end user, who opens it in a browser to OAuth their individual social accounts. Authentication: pass your account API key as `Authorization: Bearer <key>` and the TARGET sub-profile's key either as the `profileKey` argument or the `Profile-Key` header (the argument takes precedence). That Profile Key is REQUIRED and identifies whose linking page the URL opens. You do NOT supply a private key or a domain: nothing is signed, and the server resolves the account's own onboarding domain, so nothing secret enters the conversation. What you get back: `token` is an OPAQUE link-session token (not a JWT — do not try to decode it), and `url` carries it as `?session=<token>`. Th…

Generate AI-written social post copy from a topic or media. Provide `text` (a topic/brief), `mediaUrls` (public image URLs to caption), or both — at least one is required. Returns DRAFT copy only — does NOT publish. Feed the result to validate_post, then create_post. Notes: `hashtags` defaults to true. Token usage is returned in the response.

Get recommended hashtags for a keyword, sourced from TikTok view-count data. Required: `keyword`. A linked TikTok account is required (the API returns an error otherwise). Notes: To generate hashtags from a full post body instead of a single keyword, use generate_post (which can include hashtags) rather than this tool.

Register an HTTPS endpoint to receive Ayrshare event notifications for a given action. Returns the registered webhook record. Notes: re-registering the same (action, url, source) updates the existing record; secrets are write-only and never returned by list_webhooks.

Remove a previously registered webhook subscription for the given action. Returns confirmation of the removed subscription. Notes: only stops future deliveries; pass `profileKey` as an argument or via the `Profile-Key` header to target a sub-profile's subscription.

List webhook subscriptions for the authenticated account. Returns webhook records (action, url, source, timestamps) without secrets (those are write-only). Notes: without allWebhooks=true the list scopes to the current profile only; use register_webhook / unregister_webhook to manage subscriptions.

List the ad accounts the linked account on this platform can spend from. Use the accountId values returned wherever an ads tool asks for accountId. Requires the Ads add-on; without it the call returns Error 403 (code 399).

Search the platform's targeting options before boosting a post. kind 'interests' returns interest ids for audience targeting (search is required); 'regions' and 'cities' return location keys for geographic targeting. Each kind takes only its own arguments, marked in their descriptions. Requires the Ads add-on.

List boosted ads, filtered by campaign, account, ad or post. At least one of campaignId, accountId, adId, postId or socialPostId is required. status only reliably filters post lookups, so check each ad's status in the result. Requires the Ads add-on.

Change a boosted ad's state. This controls real ad spend: status PAUSED stops spending, ACTIVE resumes it, DELETED or ARCHIVED retires the ad. The same status is also set on the ad's ad set and campaign, so other ads in that ad set or campaign change with it, except a campaign or ad set the boost was attached to with attachTo, which keeps its own status. The ad runs only while the campaign and ad set above it are active. Use it when an ad is costing more than intended. Get adId from list_ads. Requires the Ads add-on.

Spend and performance history for boosted ads over a date window. Use it to see what an ad has actually cost. Requires the Ads add-on.

Boost a published post as an ad. This spends real money from the ad account. Unless you say otherwise, the ad is active, starts now and has no end date: set status paused or schedule.end to limit it. Give schedule dates as ISO 8601 date-times, such as 2026-10-10T09:00:00Z. Supply postId (the Ayrshare post id) or socialPostId (the network's own id), and accountId from list_ad_accounts. Settings only one platform has go under platformOptions, keyed by platform. On facebook and instagram, platformOptions.<platform>.adName and .bidAmount are required, for example { "facebook": { "adName": "Autumn sale", "bidAmount": 2 } }. With attachTo.adSetId, leave out budget, targeting and bidAmount: the existing ad set keeps its own. Send a new idempotencyKey (such as a UUID) with each boost, and retry with the same key and arguments: a retry returns the first response instead of paying for a second ad, or Error 409 while the first is still in progress; never retry with a new key. Use update_ad with…