ttinyposter
Get started
Codex

Use tinyposter from Codex (and other coding agents)

Codex, Cursor, Claude Code, Aider, any AI agent can use tinyposter. Three paths: MCP (cleanest), the CLI, or raw HTTP.

Pick your path

Three options, in order of preference
  • Path A, MCP (recommended). Codex CLI talks straight to tinyposter's MCP server. No tools to install, no scripts to write. Best if your agent supports MCP.
  • Path B, The CLI. Install tinyposter as a global command. Works in any agent that can run shell.
  • Path C, Raw HTTP via curl. Zero install. Works literally everywhere.
Free to connect
You can hook up your agent and make your first post on the free plan. Free comes with 1 post so you can try it. Scheduling, the queue, autolists, and posting more than once need a paid plan. Upgrade any time from billing.

Path A, MCP via Codex CLI (recommended)

Codex CLI reads MCP servers from ~/.codex/config.toml. Add a single block and tinyposter's tools become available to the agent automatically.

  1. 01

    Get a token

    Open your tokens page. Click Create token, name it “Codex,” copy the tp_… string. It only shows once.

  2. 02

    Edit ~/.codex/config.toml

    Add this block (create the file if it doesn't exist). On macOS/Linux the file is at ~/.codex/config.toml; on Windows it's %USERPROFILE%\.codex\config.toml.

    ~/.codex/config.tomltoml
    [mcp_servers.tinyposter]
url = "https://tinyposter.app/api/mcp"
http_headers = { Authorization = "Bearer tp_PASTE_YOUR_TOKEN_HERE" }

    Replace tp_PASTE_YOUR_TOKEN_HERE with your token. Keep the word Bearer and the space.

    Prefer an env var?
    Codex CLI also supports bearer_token_env_var = "TINYPOSTER_TOKEN" as a drop-in replacement for http_headers. Export the token in your shell, point Codex at the env var name, and the secret never sits in a file.
  3. 03

    Restart Codex and verify

    Quit and re-open Codex. In any session, run /mcp, you should see tinyposter listed, along with its tools.

    Try asking:

    text
    Use tinyposter to list my connected social accounts.

Path B, Use the CLI

If your agent doesn't do MCP (older Codex builds, generic shell agents) but it can run terminal commands, install the tinyposter CLI.

  1. 01

    Install the CLI

    From a terminal, run:

    bash
    npm install -g tinyposter

    Or skip install and use it on demand:

    bash
    npx tinyposter <command>

    Needs Node.js 18 or newer. If you don't have Node, get it at nodejs.org.

  2. 02

    Set the token

    Get a token from your tokens page. Then either:

    Option 1, interactive:

    bash
    tinyposter login

    Option 2, environment variable (best for agents/CI):

    bash
    export TINYPOSTER_TOKEN=tp_paste_your_token_here
  3. 03

    Tell your agent to use it

    Most agents already know how to run terminal commands. Drop these instructions into your project notes or system prompt:

    text
    When the user asks you to post to social media, use the tinyposter CLI:
- tinyposter accounts          # list connected platforms
- tinyposter post "<text>" --to PLATFORMS
- tinyposter schedule "<text>" --to PLATFORMS --at <ISO datetime>
- tinyposter list              # see recent posts
- tinyposter cancel <id>       # cancel a scheduled post
Pass --json to get machine-readable output.

Path C, Raw HTTP with curl

If you can't install anything, every agent that runs shell can use curl. Set your token in an env var, then:

bash
export TINYPOSTER_TOKEN=tp_paste_your_token

# List connected accounts
curl -s https://tinyposter.app/api/v1/accounts \
  -H "Authorization: Bearer $TINYPOSTER_TOKEN"

# Post to multiple platforms
curl -s https://tinyposter.app/api/v1/posts \
  -H "Authorization: Bearer $TINYPOSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"hello from my agent","platforms":["TWITTER","LINKEDIN"]}'

# Schedule for later
curl -s https://tinyposter.app/api/v1/posts \
  -H "Authorization: Bearer $TINYPOSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"sunday note","platforms":["THREADS"],"scheduled_at":"2026-05-03T13:00:00Z"}'

Cursor specific

Cursor supports MCP natively (no CLI needed). Full walkthrough on the MCP page under “Cursor.” If you want the CLI path instead, drop the same instructions from Path B into your .cursorrules or .cursor/rules.md.

Claude Code specific

For Claude Code, MCP is the cleanest path, see the Claude guide. If you want the CLI for some reason, install it as in Path B and add a note to your CLAUDE.md:

markdown
# Social posting

Use the `tinyposter` CLI for any social media tasks.
Token is in `$TINYPOSTER_TOKEN`. Run `tinyposter help` to see commands.

Troubleshooting

▸Codex doesn't see tinyposter after I edit config.toml

Quit Codex fully and re-open. The TOML file is only read on launch. Also check the file is at the right path (~/.codex/config.toml on Mac/Linux) and that the table header ([mcp_servers.tinyposter]) plus the http_headers inline table are spelled exactly as shown.

▸The agent says command not found

Either run with npx tinyposter instead of tinyposter, or install globally with npm install -g tinyposter. Check Node 18+ is installed: node --version.

▸It says 'Not logged in'

Either run tinyposter login once on your machine, or set TINYPOSTER_TOKEN in the agent's environment. For CI, set it as a secret.

▸I want to test without posting for real

Run tinyposter accounts or tinyposter usage, they don't consume posts. There's no sandbox mode (yet); for real posts you can pick a niche platform like Mastodon or Bluesky for low-stakes testing.

Next