# PostClock MCP server

Post from Claude, ChatGPT, Cursor or Codex. Server URL: `https://postclock.social/api/mcp` (streamable HTTP).
Sign in with OAuth, or send `Authorization: Bearer pc_…` with an API key from **Developers → API keys**.
The REST API is documented in [openapi.json](https://postclock.social/openapi.json).

## Tools

| Tool                 | REST call                       | Notes                                                                    |
| -------------------- | ------------------------------- | ------------------------------------------------------------------------ |
| `list_accounts`      | `GET /accounts`                 | Read only                                                                |
| `connect_account`    | `POST /invite-links`            | A one-time link the user opens to connect an account                     |
| `get_tiktok_creator` | `GET /creator/{id}`             | Nickname and allowed privacy levels, before any TikTok post              |
| `upload_media`       | `POST /media`                   | Returns `uploadUrl` (PUT the file) and `mediaUrl`                        |
| `create_post`        | `POST /posts`                   | `when`: `draft` (default), `now`, `scheduled`, `queue`                   |
| `list_posts`         | `GET /posts`                    | Read only                                                                |
| `get_post`           | `GET /posts/{id}`               | Read only, with deliveries                                               |
| `cancel_post`        | `POST /posts/{id}/cancel`       |                                                                          |
| `list_inbox`         | `GET /inbox`                    | Read only                                                                |
| `reply_to_comment`   | `POST /inbox/reply`             | Public reply as the account                                              |

### Publishing rules

- `create_post` makes a draft unless `when` is `now`, `scheduled` or `queue`. Those also need
  `userConfirmed: true`; without it the call returns an error and sends nothing. The tool description tells
  the model to set it only after the user explicitly asked to publish that post. `reply_to_comment` works the
  same way. Both tools carry `destructiveHint: true`, so Claude and ChatGPT ask the user before running them.
- `status`, `publishNow` and `queue` passed directly are ignored; only `when` sets them.
- Pass `idempotencyKey` to `create_post` and repeat it when retrying the same post; PostClock then never sends
  it twice.
- TikTok: the API refuses a scheduled TikTok post without `options.tiktokPrivacy`, `options.consent` and
  `options.duration`, and checks the privacy level against the creator's allowed levels when it publishes. The
  tool descriptions tell the model to call `get_tiktok_creator`, show the nickname, let the user choose the
  privacy level, and get the user's agreement to TikTok's Music Usage Confirmation (and Branded Content Policy
  for paid partnerships) before setting `consent`.
- Chat apps (Claude.ai, ChatGPT) cannot upload a local file. They can post text, or media already at a URL
  PostClock accepts. Coding agents (Claude Code, Codex, Cursor) can `PUT` a file to `uploadUrl` with `curl`.

## Setup

Create a key in **Developers → API keys** for the header options. A **Read only** key lets the AI app read
accounts, posts and the inbox but never post. Apps you sign in with OAuth are listed under **Connected AI apps**,
where you can revoke them.

### Claude Code

```bash
claude mcp add --transport http postclock https://postclock.social/api/mcp --header "Authorization: Bearer $POSTCLOCK_API_KEY"
```

Or without `--header`, then run `/mcp` in Claude Code and sign in to PostClock.

### Claude.ai and Claude Desktop

**Customize → Connectors → Add custom connector**. Name `PostClock`, URL
`https://postclock.social/api/mcp`. Sign in to PostClock and press **Allow**. Team and Enterprise owners add it
in **Organization settings → Connectors → Add → Custom → Web**. Desktop uses the same connectors as claude.ai.

### ChatGPT

ChatGPT connects with OAuth only. Turn on **Settings → Apps → Advanced settings → Developer mode**, then add
a custom MCP server with the URL `https://postclock.social/api/mcp` and OAuth. Availability of write actions
depends on the ChatGPT plan.

### Cursor

`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "postclock": {
      "url": "https://postclock.social/api/mcp",
      "headers": { "Authorization": "Bearer ${env:POSTCLOCK_API_KEY}" }
    }
  }
}
```

Leave out `headers` to sign in with OAuth instead, or use the one-click install:
[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=postclock&config=eyJ1cmwiOiJodHRwczovL3Bvc3RjbG9jay5zb2NpYWwvYXBpL21jcCJ9).

### VS Code

[Install in VS Code](https://vscode.dev/redirect/mcp/install?name=postclock&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fpostclock.social%2Fapi%2Fmcp%22%7D)
signs in with OAuth. Or add it to `.vscode/mcp.json` with a key:

```json
{
  "servers": {
    "postclock": {
      "type": "http",
      "url": "https://postclock.social/api/mcp",
      "headers": { "Authorization": "Bearer ${input:postclock-key}" }
    }
  },
  "inputs": [{ "id": "postclock-key", "type": "promptString", "description": "PostClock API key", "password": true }]
}
```

### Codex

`~/.codex/config.toml`:

```toml
[mcp_servers.postclock]
url = "https://postclock.social/api/mcp"
bearer_token_env_var = "POSTCLOCK_API_KEY"
```

Or leave out `bearer_token_env_var` and run `codex mcp login postclock`.