sparkshare-mcp

MCP server for SparkShare: let Claude Code, Codex, Claude Desktop and other AI agents publish text, images and video to your LinkedIn profile, and queue posts for X that the SparkShare Chrome extension fills in for you. Facebook Pages and Instagram follow once Meta has approved SparkShare.

Your agent writes the post; SparkShare publishes it. The agent shows you the exact text for each platform and publishes only after you say yes.

Setup

1. Create an account on SparkShare and connect LinkedIn in the dashboard. Facebook Pages and Instagram are connected there too once they are open to everyone (they wait for Meta's app review). X needs no connecting.
2. Sign in on this computer (needs Node.js 18+):

   npx -y sparkshare-mcp login

   Your browser opens SparkShare; sign in with Google if asked and click Authorize (OAuth 2.1 with PKCE). A key is saved in ~/.sparkshare/credentials.json and every MCP client on this computer finds it, including desktop apps that do not see your shell's environment variables. Nothing to copy or paste; signing in again replaces this computer's previous key. Without a browser use --no-browser (prints the link) or --paste (paste a key created in the dashboard).
3. Add the server to your agent:
   • Claude Code: claude mcp add sparkshare -- npx -y sparkshare-mcp or install the plugin, which also brings a skill with the publishing rules: /plugin marketplace add stimQQ/sparkshare-mcp then /plugin install sparkshare@sparkshare
   • Codex: codex mcp add sparkshare -- npx -y sparkshare-mcp or the plugin: codex plugin marketplace add stimQQ/sparkshare-mcp then codex plugin add sparkshare@sparkshare
   • Claude Desktop, Cursor and others:

     { "mcpServers": { "sparkshare": { "command": "npx", "args": ["-y", "sparkshare-mcp"] } } }

Then ask in plain words: "Write a LinkedIn post about this release and share the screenshot on Instagram and X."

Tools

| Tool | What it does | |---|---| | list_accounts | The accounts you can post to, with their ids. x is always there. | | publish_post | Publish one post (text, optional images or video from local paths, https URLs or upload ids, optional link) to some accounts, with optional per-account text. Every target is checked first; if any has a problem, nothing is published. | | upload_media | Upload one image or video ahead of time and get its id; use it for videos so no single call runs long. | | get_media | Whether an uploaded file is ready (videos are processed for a minute or two after uploading). | | get_post | Status and links of a post, e.g. while a platform is still processing a video. | | recent_posts | Your latest posts, so a failed call can be checked before retrying. |

How X works

X's API charges per post, so SparkShare does not post to X for you. The post waits in the SparkShare Chrome extension: click it, choose Fill on X, and X's composer opens with the text, images and video in place; you check it and press Post. Without the extension, publish_post also returns a link that opens X with the text only.

Platform rules the server enforces

• Media per post: X up to 4 images or 1 video; Facebook up to 10 images or 1 video; LinkedIn up to 20 images or 1 video; Instagram 1 to 10 images and videos (a carousel), images between 4:5 and 1.91:1.
• Video: MP4 or MOV up to 300 MB and 30 minutes; SparkShare converts it to H.264 MP4 (up to 1920 px) for publishing. Instagram Reels 3 s to 15 min, LinkedIn 3 s to 30 min.
• Text: Instagram captions up to 2,200 characters and 30 hashtags; LinkedIn up to 3,000; Facebook up to 63,206; X warns above 280 weighted characters (CJK and emoji count double, links 23).
• Images up to 20 MB are converted to JPEG, at most 2048 px on the longer side (transparency becomes white).
• Uploaded files are kept for 30 days.

Commands

sparkshare-mcp              run the MCP server on stdio
sparkshare-mcp login        authorize in the browser (--no-browser | --paste | --stdin)
sparkshare-mcp status       show which account the saved key belongs to
sparkshare-mcp logout       delete the saved key

Environment: SPARKSHARE_API_KEY (a sk_live_u_… key, used before the saved key), SPARKSHARE_CREDENTIALS_FILE, SPARKSHARE_URL (site URL; for local development http://localhost:3031).

Development

pnpm install && pnpm build
# against a local SparkShare (PUBLISH_DRY_RUN=true) on a local backend-hub, see ../README.md:
SPARKSHARE_URL=http://localhost:3031 pnpm smoke

This folder is part of the SparkShare repository (the site lives next to it in web/). The smoke test creates the dev user with ../web/scripts/dev-seed.ts, drives every tool, runs sparkshare-mcp login against the real sign-in (approving on the site the way a browser would) and deletes the dev user at the end.