meta-flywheel-mcp — Deterministic Facebook, Instagram & Threads Lead-Magnet Engine + MCP Server

meta-flywheel-mcp is a zero-dependency Python engine and Model Context Protocol (MCP) server for publishing technical stories across Facebook Pages, Instagram Professional, and Threads while fulfilling keyword comments via Meta's official Private Replies API. It enforces <500 UTF-8 byte Threads auto-chaining, SQLite partial-retry idempotency, <1ms HMAC-SHA256 webhook verification, and single-bubble DM delivery with 0 MB VRAM overhead.

Quick Start

No terminal wrestling required: click GitHub's Copy button on the top-right of any snippet below, or hand the single prompt in Step 1 directly to your AI coding agent (Claude Code, Cursor, Antigravity, Codex, or OpenCode) and let it handle setup end-to-end via llms.txt.

1. Let Your AI Agent Install It For You (1-Click Copy)

Install and configure https://github.com/cynthiaschomp/meta-flywheel-mcp in this project using its llms.txt and docs/getting-started.md, then run a quick check to confirm everything works.

2. Terminal Install (1-Click Copy)

git clone https://github.com/cynthiaschomp/meta-flywheel-mcp.git && cd meta-flywheel-mcp && python3 -m meta_flywheel.mcp_server --doctor --dry-run

3. 5-Line MCP Config (Claude Desktop, Cursor, Antigravity, OpenCode)

{
  "mcpServers": {
    "meta-flywheel-mcp": {
      "command": "python3",
      "args": [
        "-m",
        "meta_flywheel.mcp_server",
        "--mcp",
        "--dry-run"
      ]
    }
  }
}

4. Programmatic SDK / CLI Usage

from meta_flywheel import adapt_campaign_copy

payload = adapt_campaign_copy(
    brief="Our dashboard claimed 4.2x ROAS while net cash dropped by $14,200.",
    repo_url="https://github.com/cynthiaschomp/roas-to-cash-mcp",
    booking_url="https://cynthiaschomp.com/book",
    keyword="ROAS",
)
print(payload["threads"]["post_1_bytes"], payload["threads"]["post_2"])

Related MCP server: meta-social-mcp

Documentation

• Getting Started & Full Setup Guide — Step-by-step installation, configuration, and examples

• AI Agent Context (llms.txt) — Single-fetch <1,500-token SDK, CLI & architecture reference

• MCP Registry Manifest (server.json) — Official stdio tool & registry metadata

Why Technical Founders & AI Workflows Need This

• Link suppression & Threads byte-count failures — Keeps feed posts link-free, enforces exact UTF-8 byte counting (<= 500 bytes across multi-byte emojis), strips 'link in bio' or 'DM me' bait, and auto-chains links in Thread #2 via reply_to_id.

• Duplicate posts on partial API timeouts — Tracks PENDING -> STAGED -> CONTAINER_CREATED -> PUBLISHED | FAILED per channel in SQLite so retry_failed_channels retries only failed surfaces without double-posting.

• Infinite bot reply loops & multi-bubble DM lockouts — Drops self-authored webhook events immediately, deduplicates (platform, comment_id) and (campaign_id, commenter_id), and combines repo + booking URLs into one atomic Private Reply bubble.

Comparison

Architecture

Master Brief + Public URLs -> [Copy Adapter & 200-OK Gate] -> [SQLite Job Spine] -> FB / IG / Threads #1+#2 -> [HMAC Webhook + Self-Author Breaker] -> Atomic Private Reply DM

Benchmarks

FAQ

How do I connect meta-flywheel-mcp to Claude Code, Cursor, or another MCP client?

Add the 5-line mcpServers block in Quick Start pointing to python3 -m meta_flywheel.mcp_server --mcp --dry-run, and export META_APP_ID plus META_APP_SECRET in your environment when switching to live Graph API calls.

How do I prevent duplicate Facebook or Instagram posts when Threads times out?

Call flywheel_retry_failed (or retry_failed_channels(store, job_id=...)). Every channel transitions independently in SQLite, and any surface already in PUBLISHED is strictly skipped.

How do I avoid Meta's 24-hour messaging lockout when sending both a GitHub link and booking link?

Meta allows only one unsolicited Private Reply message per comment_id until the user responds. build_atomic_private_reply_payload combines both the GitHub repository link and booking link into a single atomic DM bubble alongside a public Message Requests nudge.

Who Built It

Cynthia Schomp

I run a web design, marketing, and AI systems studio—building practical software, agent infrastructure, and developer tools I need in production first, and sharing reusable building blocks openly so other builders can move faster too.

Connect: GitHub  ·  Website  ·  Contact

Feedback

Questions, bug reports, benchmark comparisons, or ideas for what you need next? Open an issue or start a thread in Discussions—real-world developer feedback directly shapes the roadmap.

License: Apache-2.0 · Attribution required via NOTICE