{ "markdown": "\n

TikTok Agent Publisher

\n\n
\n \"TikTok\n
\n\n

\n Agent-first TikTok Content Posting API CLI + MCP.
Dry-run safe, OAuth readiness checks, structured output for any agent runtime.\n

\n\n

\n \"npm\n \"npm\n \"License\n \"Built\n

\n\n

\n \"GitHub\n \"CI\n \"Part\n \"Category\"\n

\n\n> ⭐ **If this agent-first tool helps your workflow, please star the repo.** Stars make this tooling easier for other builders to discover and help Delx keep shipping open infrastructure.
\n> 🧱 Part of the [Delx agent stack](https://github.com/davidmosiah) — 15 open-source MCP servers across **body, reach and coordination**.\n\n---\n\n\n\nLocal-first TikTok Content Posting API tooling for AI agents. It gives Codex, Claude, Cursor, Hermes, OpenClaw and other MCP clients a safe way to check readiness, build OAuth URLs, dry-run publish flows and upload TikTok videos only when live mode is explicitly enabled.\n\nUse it when an agent needs to publish or inspect TikTok content without browser automation, hidden state or token leakage.\n\n## Why It Exists\n\nMost social publishing scripts are built for humans at a terminal. Agents need a different contract:\n\n- a manifest that explains install/runtime rules\n- a connection status tool before write operations\n- privacy boundaries that never return token values\n- dry-run by default\n- structured JSON outputs for planning, retries and audit trails\n\nThis repo packages that contract around TikTok's official Content Posting API.\n\n## Install\n\n```bash\nnpm install -g tiktok-agent-publisher\n```\n\nOr run without installing:\n\n```bash\nnpm exec --yes --package=tiktok-agent-publisher -- tiktok-agent-publisher doctor\n```\n\n## First Post (Dry-Run) Walkthrough\n\nNo TikTok credentials are required to try this. With no `.env`, dry-run is on by\ndefault, so every command below returns structured JSON without touching the live\nAPI. This is the exact sequence an agent should follow before its first real post.\nThe outputs are real CLI runs, lightly trimmed.\n\n**1. Check readiness.** `doctor` reports mode and what is still missing — never any\ntoken values.\n\n```bash\n$ tiktok-agent-publisher doctor\n{\n \"ok\": true,\n \"dry_run\": true,\n \"configured\": {\n \"client_key\": false,\n \"client_secret\": false,\n \"access_token\": false,\n \"refresh_token\": false,\n \"public_media_base_url\": false,\n \"supabase_storage\": false\n },\n \"missing\": [\n \"TIKTOK_CLIENT_KEY\",\n \"TIKTOK_CLIENT_SECRET\",\n \"TIKTOK_ACCESS_TOKEN\",\n \"TIKTOK_REFRESH_TOKEN\"\n ],\n \"ready_for_live_publish\": false,\n \"ready_for_direct_video_upload\": false,\n \"next_steps\": [\n \"Current mode is dry-run. Use dry-run to validate agent workflow before live posting.\"\n ]\n}\n```\n\n**2. Confirm the privacy boundaries.** `privacy-audit` states what stays local and\nwhat is sent to TikTok, so the agent can reason about the contract before any write.\n\n```bash\n$ tiktok-agent-publisher privacy-audit\n{\n \"project\": \"tiktok-agent-publisher\",\n \"secrets_returned_to_agent\": false,\n \"token_storage\": \"Environment variables or local .env with user-only file permissions; tokens are never returned by tools.\",\n \"safety_rules\": [\n \"Dry-run is the default.\",\n \"Only post content the user owns or has permission to publish.\",\n \"Use explicit confirmation before live direct posting.\"\n ]\n}\n```\n\n**3. Build the publish payload (dry-run).** This validates the job shape and caption\nwithout uploading anything. `result.platformPostId` is a synthetic `dryrun_*` id and\n`raw.dryRun` is `true`, so you can wire up retries and audit logging safely.\n\n```bash\n$ tiktok-agent-publisher publish-video \\\n --video ./short.mp4 \\\n --caption \"First agent post — testing the dry-run flow\" \\\n --title \"Hello from an agent\"\n{\n \"ok\": true,\n \"dry_run\": true,\n \"job\": {\n \"id\": \"tiktok_1780082349025\",\n \"platform\": \"tiktok\",\n \"status\": \"queued\",\n \"caption\": \"First agent post — testing the dry-run flow\",\n \"mediaPaths\": [\"./short.mp4\"],\n \"metadata\": { \"title\": \"Hello from an agent\" }\n },\n \"result\": {\n \"provider\": \"tiktok_official\",\n \"platformPostId\": \"dryrun_1780082349025\",\n \"raw\": { \"dryRun\": true, \"jobId\": \"tiktok_1780082349025\" }\n }\n}\n```\n\n**4. Poll status (dry-run).** `publish-status` returns a `DRY_RUN` status so the\npolling loop can be exercised end to end.\n\n```bash\n$ tiktok-agent-publisher publish-status --publish-id dryrun_1780082349025\n{ \"dryRun\": true, \"publishId\": \"dryrun_1780082349025\", \"status\": \"DRY_RUN\" }\n```\n\n**5. List recent videos (dry-run).** Returns an empty, well-formed list — the same\nshape the live API returns, so post-publish confirmation code works unchanged.\n\n```bash\n$ tiktok-agent-publisher list-videos --max-count 5\n{ \"dryRun\": true, \"videos\": [], \"cursor\": null, \"has_more\": false }\n```\n\n**Going live.** Fill in `TIKTOK_CLIENT_KEY` / `TIKTOK_CLIENT_SECRET` (and complete\nOAuth — see [`auth-url`](#cli)), confirm `doctor` reports `ready_for_live_publish: true`,\nthen set `TIKTOK_DRY_RUN=false`. The same five commands then operate against the real\nContent Posting API.\n\n## CLI\n\n```bash\ntiktok-agent-publisher manifest --client codex\ntiktok-agent-publisher doctor\ntiktok-agent-publisher privacy-audit\ntiktok-agent-publisher auth-url --redirect-uri http://localhost:8787/callback\ntiktok-agent-publisher publish-video --video ./short.mp4 --caption \"Launch copy\"\ntiktok-agent-publisher publish-status --publish-id \ntiktok-agent-publisher list-videos --max-count 10\n```\n\nDry-run is enabled by default. Set `TIKTOK_DRY_RUN=false` only after `doctor` is clean and you are ready for live API calls.\n\n## MCP\n\nStdio:\n\n```bash\ntiktok-agent-mcp\n```\n\n## HTTP (v2 stateless)\n\nDefault is **stdio**. Optional Streamable HTTP — no session id, JSON responses, loopback only:\n\n```bash\nnpx -y -p tiktok-agent-publisher tiktok-agent-mcp --http\n# GET http://127.0.0.1:3031/health\n# POST http://127.0.0.1:3031/mcp (sessionless)\n```\n\nEnv: `TIKTOK_MCP_HOST`, `TIKTOK_MCP_PORT`, `TIKTOK_MCP_TRANSPORT=http`.\n\nHermes-style config:\n\n```yaml\nmcp_servers:\n tiktok:\n command: npx\n args: [\"-y\", \"tiktok-agent-publisher\"]\n sampling:\n enabled: false\n```\n\nRecommended first calls:\n\n1. `tiktok_connection_status`\n2. `tiktok_privacy_audit`\n3. `tiktok_publish_video`\n\n## Agent Surfaces\n\n| Tool | Purpose |\n|---|---|\n| `tiktok_agent_manifest` | Install/runtime guidance for Codex, Claude, Cursor, Hermes and OpenClaw |\n| `tiktok_connection_status` | Dry-run, OAuth and media-hosting readiness without token values |\n| `tiktok_privacy_audit` | Local file, token and live-publish boundaries |\n| `tiktok_publish_video` | Dry-run or live video publish flow |\n| `tiktok_publish_status` | Publish-status polling |\n| `tiktok_list_videos` | Recent video list for post-publish checks |\n\n## Copy-Paste Agent Prompt\n\n```text\nUse tiktok-agent-publisher. First call tiktok_connection_status and tiktok_privacy_audit.\nIf dry-run is enabled, build the publish payload only. Do not request or print token values.\n```\n\n## Configuration\n\nCopy `.env.example` to `.env` and fill only the values you need. Do not commit `.env`, token files or `.agent-data/`.\n\nFor video inbox uploads, a local file can be uploaded directly through TikTok's upload URL. Photo and pull-from-url workflows can use Supabase Storage or another public media host.\n\n## Safety Model\n\n- Tokens are read from environment or local `.env`; tool responses never include token values.\n- Live publishing is disabled unless `TIKTOK_DRY_RUN=false`.\n- OAuth PKCE verifier is persisted locally in `.agent-data/` and not returned in MCP output.\n- The package uses TikTok's official API surfaces; it does not automate a browser session.\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run check\n```\n\n---\n\n## 📧 Contact & Support\n\n- 📨 **support@delx.ai** — general questions, integration help, partnerships\n- 🐛 **Bug reports / feature requests** — [GitHub Issues](https://github.com/davidmosiah/tiktok-agent-publisher/issues)\n- 🐦 **Updates** — [@delx369](https://x.com/delx369) on X\n- 🌐 **Site** — [wellness.delx.ai](https://wellness.delx.ai)\n\n", "bytes": 9779, "sha": "dd97fb5f71773faf0f3cdf6b3e43a0f21465a3b3356f7f8344b1b30089ed16e7", "repo_slug": "davidmosiah/tiktok-agent-publisher", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_davidmosiah_tiktok_agent_publi_b5cb7f59/readme" }