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

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:

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:

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

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:

pnpm build
pnpm dashboard

Open 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:

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 for the exact D1, secret, build, and callback configuration.

Run all checks:

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:

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

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

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:

[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.

{
  "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.

{
  "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

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.