> Markdown version of https://socialcannon.app/docs/claude (Claude connector). The index of all SocialCannon documentation is at https://socialcannon.app/llms.txt.

# SocialCannon connector for Claude

The SocialCannon connector lets Claude draft, schedule and publish posts on the social accounts you connected in SocialCannon, read your calendar and comments, and reply where your plan allows. You sign in to SocialCannon and approve the connection once; no API key goes into the chat.

The connector is in testing and is not yet open to every SocialCannon account. Claude Desktop can use SocialCannon today through the local MCP server described in the [MCP guide](https://socialcannon.app/guides/mcp-server-social-media.md).

## Connect

You need a SocialCannon account. The Free plan works, and a practice post needs no connected social account.

The connector URL and setup steps will appear here when the connector opens to every account.

## Start with a practice post

Ask Claude to make a practice post. It goes to the sandbox destination (account ID `sandbox`): SocialCannon simulates publishing, sends nothing to any network and returns a practice link. Each SocialCannon account includes 100 practice posts, and they do not count against your plan’s post allowance. A post to any other account is real and appears publicly on that network.

## Approvals

Every tool carries a read-only or a changes-data annotation. Claude runs read-only tools without asking and asks you to approve each tool that changes data, such as publishing, scheduling, replying, retrying or deleting, unless you change that tool’s permission in Claude’s connector settings.

## Tools

### Read-only (13)

- **List platforms** (`list_platforms`): List all supported social media platforms and their capabilities
- **List accounts** (`list_accounts`): List the social media accounts connected to this SocialCannon account. Accounts are connected and disconnected in the SocialCannon dashboard. A practice post needs no connected account: create_post accepts accountId "sandbox".
- **Get TikTok creator info** (`get_tiktok_creator_info`): Fetch a connected TikTok account's current posting capabilities: the privacy levels it allows (privacyLevelOptions), whether Comment/Duet/Stitch are disabled account-side, the creator nickname/username, and max video duration. Required before creating a TikTok post: create_post needs a privacyLevel from privacyLevelOptions, and an interaction the creator has disabled must stay disabled.
- **List posts** (`list_posts`): List social media posts with optional filters
- **Get post** (`get_post`): Get details of a specific post by ID
- **Get calendar** (`get_calendar`): Get a content calendar view showing posts, gaps, and summary stats for a date range
- **Get post analytics** (`get_post_analytics`): Get engagement metrics (likes, comments, shares, impressions) for a published post
- **Get analytics summary** (`get_analytics_summary`): Get aggregate analytics across all posts for a date range
- **Get engagements** (`get_engagements`): List stored engagements (comments/replies) with optional filters
- **List unread engagements** (`list_unread_engagements`): List all unread engagements (shortcut for get_engagements with isRead=false)
- **Get A/B test results** (`get_ab_test_results`): Get A/B test results with per-variant analytics and winner determination
- **Get best posting times** (`get_best_posting_times`): Get recommended posting times based on historical engagement data for an account
- **Get optimal slot** (`get_optimal_slot`): Find the single best available posting time by combining engagement data with calendar availability. Returns the next open slot ranked by historical performance. Requires Pro tier.

### Changes your data (10)

- **Create post** (`create_post`): Create and publish or schedule a social media post on a connected account. accountId "sandbox" makes a practice post instead: it is simulated, publishes nowhere and returns a sandbox link. Supply a stable idempotencyKey and reuse it for retries; a new key deliberately creates a new post. ACCOUNT_ACTION_REQUIRED means review the owned account recovery guidance; do not blindly retry or replay earlier uncertain publications. Account recovery uses POST /api/v1/accounts/:id/recovery and a consented new verification post. For TikTok, privacyLevel is REQUIRED — call get_tiktok_creator_info first to fetch the account's allowed privacy levels and which interactions (comment/duet/stitch) are disabled, and never enable an interaction the creator has disabled.
- **Update post** (`update_post`): Update a draft or scheduled post, or explicitly reschedule an awaiting_account post after account recovery. Held posts require a future scheduledAt at least five minutes ahead and five minutes from another recovered post; recovery never republishes missed content automatically. To save held content as a draft, use REST PATCH /api/v1/posts/:id with scheduledAt:null. Existing provider-attempt and in-progress idempotency guards still apply.
- **Delete post** (`delete_post`): Delete a post with fail-closed provider compensation. Use strictCompensation=true for every provider-acknowledged, published, or reconciliation row; bodyless deletion is also provider-safe but cannot assert an expected provider ID.
- **Retry post** (`retry_post`): Repair or retry a failed single post. Provider-confirmed rows are repaired locally; uncertain rows reconcile or fail closed. Failed threads without a provider ID are not retried through this tool.
- **Create thread** (`create_thread`): Create a multi-part thread (Twitter thread, Instagram carousel, LinkedIn multi-segment post). Supply a stable idempotencyKey and reuse it for retries; a new key deliberately creates a new thread.
- **Generate tracked link** (`generate_tracked_link`): Generate a UTM-tagged URL for tracking social media traffic
- **Repurpose content** (`repurpose_content`): Repurpose content for different social media platforms using AI and return the variants for review (preview only)
- **Reply to engagement** (`reply_to_engagement`): Reply to a specific engagement (comment/reply) on the social platform
- **Create A/B test** (`create_ab_test`): Create an A/B test with content variants for a social media account. All variants publish immediately to the platform (no scheduledAt support via MCP). Each variant becomes a separate post. Auto-completes after minDurationHours and picks a winner by the chosen metric. Not supported for TikTok accounts (A/B-test variants cannot set the per-post privacy level TikTok requires) or for publish-only platforms whose post analytics are unavailable — LinkedIn and Facebook (a winner could never be determined) — rejected with code PLATFORM_UNSUPPORTED.
- **Auto-schedule a week of posts** (`auto_schedule_week`): Automatically schedule multiple posts across the next 7 days at optimal engagement times. Distributes posts to the best available time slots based on historical engagement data and calendar availability. Each post gets a unique slot. Requires Pro tier and a stable idempotency key; reuse the exact key after a timeout or partial response.

## Permissions

The consent screen lists what Claude will be able to do. Claude asks for these permissions, and a connection gets only those your SocialCannon API key also has (Settings → API Keys):

- See your posts, drafts, schedule and calendar
- Create, schedule and publish posts on your connected accounts
- Delete posts, including published posts on your connected accounts
- See which social accounts you have connected
- Read post performance and analytics
- Create tracked (UTM) links
- Read comments and replies on your posts
- Reply to comments and mark them read

Claude can never connect or disconnect social accounts, see your API secret, change your plan or manage API clients.

## Disconnect

Revoke Claude in SocialCannon under Settings → Connected assistants. The connection stops working on its next request. You can also remove the connector in Claude. Access tokens last 60 minutes and are renewed automatically; an unused connection ends after 30 days, and every connection must be approved again after 90 days.

## If something goes wrong

- **The sign-in or approval fails.** Sign in to SocialCannon in the same browser, then choose Connect in Claude again. If the consent screen says none of the requested permissions are enabled, turn them on under Settings → API Keys.
- **A tool says a plan limit was reached.** The message names the limit, for example that X publishing needs a paid plan. A single post or thread published nothing. An A/B test or a week of auto-scheduled posts may already have published or scheduled earlier items, so check them in SocialCannon before asking Claude to continue.
- **A tool says the outcome needs reconciliation or is uncertain.** The network may already have the post. Check it in SocialCannon before asking Claude to send anything again; repeating the same request with the same key never publishes twice.
- **Too many requests.** Wait a minute and try again.

Every error code and its safe next step is in the [error reference](https://socialcannon.app/docs/errors.md).

## Data and privacy

SocialCannon receives only what Claude sends to its tools, such as the text and media links of a post, and returns what that tool reads, such as your posts, calendar or comments. It never receives your Claude conversation history. For each connection SocialCannon stores the assistant’s name, the permissions you approved and when the connection was created and last used. The [privacy policy](https://socialcannon.app/privacy) covers retention and your rights.

## Support

Email [support@socialcannon.app](mailto:support@socialcannon.app). Include the time of the request and the tool name, but never an access token or API secret.