API reference

All three interfaces sit on one core, so names and behavior match across MCP, CLI, and HTTP.

MCP tools

The desktop app exposes these tools over MCP. Address targets by targets (specific accounts, recommended), platforms, or groups. Pass images as file paths or http URLs — not base64.

Status

  • get_status — confirm the app is ready (platform / account / logged-in counts).

Platforms, accounts & groups

  • list_platforms — all platforms and their capabilities.
  • list_accounts — logged-in accounts and their session state.
  • list_account_groups — account groups and members.
  • check_auth — is a platform account logged in?
  • request_login — re-login an existing account (opens a window; fresh=true forces a re-scan).
  • add_account — add a new account (supports multiple per platform).
  • set_account_label — rename an account.
  • remove_account — remove an account and clear its local session.
  • set_account_defaults — lock an account's platform-specific option defaults (e.g. the AI declaration), applied automatically on publish.

API credentials

  • list_platform_credentials — list API credentials (secrets masked).
  • set_platform_credentials — configure API credentials (e.g. a WeChat appId/appSecret).
  • remove_platform_credentials — delete a platform's credentials.

Drafts & publishing

  • create_draft — save as a draft (nothing public).
  • publish_post — attempt a real publish (returns stage / published / code); spacingMinutes > 0 staggers multiple targets into a queue.
  • publish_draft — promote an existing draft (by post id) to a real post.
  • preview_content — render Markdown to HTML with the publishing renderer.
  • list_platform_categories — the categories / columns a platform offers.

Scheduling

  • schedule_post — publish at a given time; deliver (auto / platform / local) decides whether to hand over to the platform's own scheduler, spacingMinutes staggers targets.
  • list_schedules — query scheduled tasks (pending / running / done / failed / canceled).
  • cancel_schedule — cancel a pending task; pass batchId to cancel a whole batch.

Records & metrics

  • list_posts — query publish/draft records (by platform, account, status, stage, keyword, date; paged).
  • get_post_metrics — fetch engagement (views / likes / comments / shares) — supported on some overseas platforms only.
  • get_account_overview — read account-level stats (followers, likes, last-7-day metrics) and keep local snapshots for growth.
  • list_alerts — session alerts: expired / expiring / pending retries (check before distributing).

Policy

  • get_policy / set_policy — read/write the safety policy (daily limit, de-dup, circuit breaker, blackout hours, minimum spacing).

Stock images (bring your own key)

  • search_stock_images — search Pixabay / Pexels / Unsplash for commercial-use images.
  • use_stock_image — pick one and get a public URL.

CLI commands

node bin/omnipost.js <command>. Everything needs the desktop app running except mcp and oauth-connect.

  • status · platforms · accounts
  • account add|remove|label|list <platform> — manage accounts
  • account defaults <platform> <accountId> --extras '{"aiGenerated":true}' [--category] | --clear — lock / clear the account's option defaults
  • login <platform> [--accountId] · check-auth <platform>
  • groups · group save|rm <name> (--targets|--platforms)
  • preview --doc <file.md>
  • publish --doc <file.md> (--platforms|--targets|--group) [--mode draft|publish] [--title --tags --summary --category --cover --video --canonical --baseDir] [--spacing N]
  • publish-draft <platform> <postId>
  • posts [--platform --accountId --status --stage --q --limit]
  • posts --csv [same filters] > posts.csv — export records as CSV (with the review column)
  • overview <platform> [--accountId] · alerts
  • categories <platform> [--accountId]
  • metrics <platform> (--recordId|--postId) [--accountId --force]
  • images providers|search <provider> "<query>"|use <provider> (--item|--url) [--mode cover|inline --out]
  • schedule --doc <file.md> --at "YYYY-MM-DD HH:mm" (--platforms|--targets) [--mode --baseDir] [--deliver auto|platform|local] [--spacing N]
  • schedules [--status --platform --q --batch] · schedule-cancel <id> | --batch <batch id>
  • api-config list|set|remove <platform> [--accountId] [--key value ...]
  • oauth-connect <platform> [...] — interactive OAuth (Mastodon family, LinkedIn); runs without the desktop app
  • media-test --file <image> — test the S3 image host
  • policy show|set [...]
  • mcp — start the stdio MCP server (runs without the desktop app)

--platforms targets every logged-in account on a platform; --targets csdn:default,csdn:a2 targets specific accounts.

HTTP endpoints

Localhost only, under http://127.0.0.1:8787/api/*. Highlights:

  • GET /api/health — status, port, MCP SSE address, data/log dirs.
  • GET /api/agent-tools — live MCP tool list.
  • GET /api/skill — a ready-made Claude Skill (?download=1 for a ZIP).
  • POST /api/publish/stream — streaming publish (NDJSON per-account events).
  • GET /api/posts/export.csv — records as CSV (same filters as /api/posts).
  • POST /api/schedules/batch/:batchId/cancel — cancel the still-pending tasks of a batch.

The MCP SSE endpoint is http://127.0.0.1:8787/sse (messages posted back to /mcp/messages).

Configuration

  • Data lives under ~/.omnipost/ (accounts, posts, schedules, groups, policy, license). Login cookies stay in isolated browser partitions.
  • Port defaults to 127.0.0.1:8787.
  • Environment: OMNIPOST_PORT (port), OMNIPOST_DATA_DIR (data dir), OMNIPOST_API_BASE (CLI/MCP target API).