API & MCP Reference

Connect FireBreath to Claude Code or any AI assistant using the Model Context Protocol (MCP). 21 tools for fully automated social media management.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and services. FireBreath's MCP server exposes 21 tools that an AI agent can call to create posts, upload media, schedule content, manage accounts, and analyze performance — all without leaving the AI conversation.

Setup

Add FireBreath to your AI assistant's MCP configuration. For Claude Code, add this to your .mcp.json file:

{
  "mcpServers": {
    "firebreath": {
      "command": "npx",
      "args": ["tsx", "path/to/firebreath/mcp/server.ts"]
    }
  }
}

The server reads environment variables from .env.local in the FireBreath project root.

Required Environment Variables

Variable	Purpose
`NEXT_PUBLIC_SUPABASE_URL`	Supabase project URL
`SUPABASE_SECRET_KEY`	Supabase service role key (admin access)
`TOKEN_ENCRYPTION_KEY`	AES-256-CBC key for decrypting OAuth tokens
`META_APP_ID / META_APP_SECRET`	Facebook + Instagram (Meta Graph API)
`TWITTER_CLIENT_ID / TWITTER_CLIENT_SECRET`	X/Twitter OAuth 2.0
`LINKEDIN_CLIENT_ID / LINKEDIN_CLIENT_SECRET`	LinkedIn OAuth 2.0
`TIKTOK_CLIENT_KEY / TIKTOK_CLIENT_SECRET`	TikTok Content Publishing API
`QSTASH_TOKEN`	Upstash QStash for post scheduling
`ANTHROPIC_API_KEY`	AI caption generation (Claude)

Tools Reference (21 tools)

Publishing

firebreath_create_post

Create and optionally publish a post to one or more connected accounts. Supports publish, schedule, draft, and manual actions.

Params: content, integrationIds, action, scheduledAt?, mediaUrls?, manualInstructions?

firebreath_upload_media

Upload images or videos for use in posts. Accepts a local file path or a URL.

Params: filePath | url

firebreath_publish_post

Publish a draft or scheduled post immediately.

Params: postId

firebreath_retry_post

Retry a post that failed to publish.

Params: postId

firebreath_post_thread

Post a thread (chain of tweets) on X/Twitter. Supports Tier 2 posting strategy.

Params: integrationId, tweets[]

firebreath_reply_to_post

Reply to an existing published X/Twitter post.

Params: postId, content

firebreath_approve_post

Approve (lock) or revoke approval (unlock) a post.

Params: postId, action ("approve" | "revoke")

AI Caption Generation

firebreath_generate_caption

Generate AI-powered captions for one or more platforms. Returns 2 variations per platform with character counts.

Params: prompt, platforms[], tone, language?, existingContent?, includeHashtags?

Media Staging & Batches

firebreath_list_media

List uploaded media. Use filter "ready" to find staged media.

Params: filter? ("all" | "ready"), limit?

firebreath_list_batches

List media batches grouped for posting.

Params: status? ("ready" | "posted" | "all")

firebreath_mark_media_used

Mark media or batches as used after posting.

Params: batchId | mediaIds[]

Management

firebreath_list_accounts

List all connected social media accounts with integration IDs.

firebreath_list_posts

List posts with optional state filter.

Params: state?, limit?

firebreath_get_post

Get full details of a specific post.

Params: postId

firebreath_update_post

Edit content or reschedule a post.

Params: postId, content?, scheduledAt?

firebreath_delete_post

Soft-delete a post.

Params: postId

Import & Sync

firebreath_sync_posts

Import existing posts from connected platforms. Already-imported posts are skipped.

Params: integrationId, limit?

Analytics & Learning

firebreath_get_analytics

Fetch engagement metrics for a published post. Instagram posts get media-type-specific metrics.

Params: postId

firebreath_get_channel_analytics

Get aggregate performance for a channel over a time period.

Params: integrationId, from?, to?

firebreath_get_account_insights

Instagram account-level insights: follower growth, demographics, optimal posting times.

Params: integrationId, period?, since?, until?, includeDemo?

firebreath_analyze_content

Retrieve published posts with analytics for content strategy analysis.

Params: integrationId?, limit?, sortBy?

Example Prompts

Here are some example prompts you can use with Claude Code or another MCP-compatible AI assistant:

Schedule a post to multiple platforms

"Schedule a post about our spring sale to Facebook and Instagram for tomorrow at 10 AM. Include a cheerful, promotional tone."

Post user-prepared media

"Check for any ready media batches and post them according to the instructions."

Analyze content performance

"Analyze my Instagram content from the last 30 days. What types of posts get the most engagement?"

Generate captions

"Generate captions for a post about our new product launch. Target Instagram, LinkedIn, and Twitter with a professional tone."

Weekly content planning

"Create a content calendar for next week. Schedule 2 posts per day across Instagram and Facebook based on what performed best last month."

Recommended Workflow

FireBreath splits content production into two roles: producers (who create content, typically via MCP/AI) and reviewers (who verify and lock content, typically via the web app).

1.Producer creates content — AI agent uses firebreath_create_post with action "schedule".
2.Reviewer checks content — Opens the Review page in FireBreath, reads the post, edits if needed, and clicks Approve to lock it.
3.Post publishes automatically — At the scheduled time, the post is published via the platform API.
4.Analyze and learn — Use firebreath_analyze_content to understand what works and refine your strategy.

Back to Getting Started