# sparkshare-mcp

MCP server for [SparkShare](https://sparkshare.dev): 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+):
   ```bash
   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**:
     ```json
     { "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

```bash
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.