# Threads Scheduler MCP

A free, local-first MCP server for reading, planning, scheduling, and publishing Meta Threads posts from Codex Desktop.

The current MVP implements:

- SQLite persistence and migrations
- local Meta Threads OAuth with state validation
- short-lived to long-lived access-token exchange
- account profile verification and registration
- macOS Keychain token retrieval
- a typed Threads API adapter
- `threads_list_posts`
- `threads_get_post`
- text draft creation, editing, and exact previews
- confirmation-gated immediate publishing
- confirmation-gated scheduling, rescheduling, and cancellation
- durable idempotency records and immutable scheduled snapshots
- local and Cloudflare background publishing workers
- a private hosted dashboard protected by a signed OAuth session
- structured, redacted errors

Remaining hardening and installation work is tracked in `TASKS.md`.

## Requirements

- macOS
- Node.js 22 LTS or newer
- pnpm 10
- Codex Desktop
- a Meta developer app with Threads API access

## Install

```bash
pnpm install
cp .env.example .env
pnpm build
```

Set `THREADS_GRAPH_API_VERSION` to the currently supported version shown in Meta's official Threads API documentation. Do not assume the example value is current.

## Configure Meta OAuth

In the Meta developer dashboard:

1. Create an app with the Threads use case.
2. Add your Threads account as an app tester while the app is in development mode.
3. Add this exact valid OAuth redirect URI:

   ```text
  http://127.0.0.1:8787/oauth/callback
   ```

4. Enable the permissions required by the MVP:

   ```text
   threads_basic
   threads_content_publish
   ```

5. Put the Threads app ID and Threads app secret in your local `.env`.

The redirect URI in `.env` and Meta must match exactly, including scheme, host, port, path, and trailing slash behavior.

Connect the account:

```bash
pnpm build
pnpm connect
```

Open the printed authorization URL, approve access, and return to the terminal. The local callback listens for up to five minutes. It validates the OAuth state, exchanges the code, upgrades the short-lived token to a long-lived token, verifies the profile identity, stores the token in macOS Keychain, and registers the account in SQLite.

The command never prints the app secret or access token.

## Development

```bash
pnpm dev
```

The process speaks MCP JSON-RPC over stdout. Application logs are written to stderr so they cannot corrupt the MCP transport.

## Local dashboard

Build and start the private dashboard:

```bash
pnpm build
pnpm dashboard
```

Open [http://127.0.0.1:7777](http://127.0.0.1:7777). The dashboard reads the same local SQLite database and Keychain-backed Threads connection as the MCP server. It shows connection status, recent posts, drafts, scheduled posts, and publication counts.

The server binds to the loopback interface by default and is not accessible from other computers. Override `DASHBOARD_HOST` or `DASHBOARD_PORT` only when needed; keep the host on a loopback address.

To deliver local schedules while Codex Desktop is closed, keep the worker
running:

```bash
pnpm build
pnpm worker
```

The Mac must remain awake and online. A `launchd` installer is still tracked as
follow-up work; the hosted Cloudflare version does not depend on the Mac.

## Cloudflare deployment

The repository also includes a Cloudflare Worker for the hosted dashboard, Meta OAuth, deauthorization, data deletion, D1 persistence, and hosted Threads reads.

See [Cloudflare deployment](docs/cloudflare-deployment.md) for the exact D1, secret, build, and callback configuration.

Run all checks:

```bash
pnpm check
```

## Account connection

The server starts normally without an account, but read tools return `AUTH_REQUIRED` until `pnpm connect` completes successfully.

Do not place access tokens in `.env`, source files, SQLite, shell history, or Codex configuration. The OAuth connection flow stores tokens in macOS Keychain.

## Codex Desktop configuration

The deployed Worker exposes an authenticated Streamable HTTP MCP endpoint:

```text
https://treads-mcp.elvischukwuemekaekanem.workers.dev/mcp
```

Register it with a bearer token stored in the Codex process environment:

```bash
codex mcp add threads_scheduler \
  --url https://treads-mcp.elvischukwuemekaekanem.workers.dev/mcp \
  --bearer-token-env-var THREADS_MCP_TOKEN
```

The Cloudflare `MCP_BEARER_TOKEN` secret and local
`THREADS_MCP_TOKEN` value must match. Restart Codex Desktop after changing MCP
configuration.

For local-only development, build and add a stdio MCP entry using absolute
paths:

```toml
[mcp_servers.threads_scheduler]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/Threads MCP/dist/src/index.js"]

[mcp_servers.threads_scheduler.env]
THREADS_DB_PATH = "/absolute/path/to/application-data/threads.sqlite"
THREADS_GRAPH_API_VERSION = "REPLACE_WITH_CURRENT_VERSION"
DEFAULT_TIMEZONE = "Asia/Kuala_Lumpur"
```

Do not add `THREADS_APP_SECRET` or access tokens to this configuration.

The exact Codex Desktop configuration location and syntax can evolve; verify it against the current Codex documentation during installation.

## Available tools

### `threads_list_posts`

Read the connected account's recent posts.

```json
{
  "limit": 20,
  "cursor": "optional-pagination-cursor",
  "since": "2026-07-01T00:00:00+08:00",
  "until": "2026-07-31T23:59:59+08:00"
}
```

`account_id` is optional when exactly one active account is connected.

### `threads_get_post`

Read one post by ID.

```json
{
  "post_id": "THREADS_POST_ID",
  "account_id": "optional-local-account-id"
}
```

These tools are read-only.

### Draft and publishing tools

- `threads_create_draft`
- `threads_update_draft`
- `threads_preview_draft`
- `threads_publish_now`
- `threads_publish_status`

Immediate publishing requires `confirmed: true` and a unique
`idempotency_key`.

### Scheduling tools

- `threads_schedule`
- `threads_list_scheduled`
- `threads_reschedule`
- `threads_cancel_scheduled`

Schedule creation requires an ISO 8601 time with an explicit UTC offset, an
IANA time zone, `confirmed: true`, and a unique `idempotency_key`. The scheduler
stores an immutable copy of the approved text, so later edits cannot silently
change a scheduled post.

## Local data and secrets

- SQLite stores account metadata, drafts, schedules, publications, and audit events.
- Access tokens belong in the macOS Keychain service named `threads-scheduler-mcp`.
- `.env`, databases, logs, and generated launch-agent files are ignored by Git.
- SQLite uses WAL mode, foreign keys, and a busy timeout.

## Project structure

```text
src/
  config.ts
  index.ts
  db/
  domain/
  lib/
  mcp/
  providers/threads/
  services/
  worker/
tests/
```

See `AGENTS.md` for engineering rules and `TASKS.md` for the complete deployment checklist.