Threads MCP Server & CLI

A free, open source Threads MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents post, reply, read your insights and search Threads.

Navid Moazzezby Navid Moazzez·Updated Oct 5, 2026·14 min read·
Your computer
  1. 1

    Log in once in a terminal, with your Meta app's ID and secret. It stores a 60-day token that renews itself.

    export THREADS_APP_ID=your-app-id
    export THREADS_APP_SECRET=your-app-secret
    npx -y @thenavidm/threads-mcp-cli@latest login
  2. 2

    Add it with a single command in a terminal.

    claude mcp add threads \
    -- npx -y @thenavidm/threads-mcp-cli@latest
  3. 3

    In Claude Code, type /mcp. Threads should show as connected.

    /mcp

Needs Node 22 or newer, plus the ID and secret of a Meta app with the Threads API. Make one in about 10 minutes.

It's free and open source. If it saves you time, star it on GitHub, so more people find it.

Rate this tool

This free Threads MCP server and CLI gives your AI real access to your Threads profile. It posts, replies, reads your insights and searches Threads.

It's one install with two ways in. Claude, Codex, Cursor or any other MCP app calls its 30 tools for you, and the same tools work as a CLI that agents like Claude Code, Codex and OpenCode run, or that you type yourself.

In this guide, I'll show you:

  • What the Threads MCP server & CLI is, and what you can ask it
  • How to install it and check that it works
  • When to use the MCP server, and when the CLI
  • Every tool, and how to keep your account safe

Every tool on this page comes from the server itself, and every cost was measured in Claude Code.

key_takeaways.mdTL;DR

Key takeaways

It gives Claude, Codex, Cursor and any other MCP app 30 tools to post, reply, read your insights and search Threads.
The same tools run as a CLI, which costs your AI nothing until it runs.
Posting, replying, reposting and deleting wait for your approval, and stage_post shows a post before it goes public.
Run threads-cli refresh once a month, and its token never runs out.

What is the Threads MCP server & CLI?

The Threads MCP server & CLI is a free, open source program that lets AI agents act on Threads for you, in two ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to Meta's Threads API.

The CLI is the same program as commands. threads-cli get-top-posts runs the same code your AI runs when you ask which posts worked, whether an agent like Claude Code runs it or you do.

In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Threads. My guide to building an AI operating system names Threads among the tools it reaches, and here's how I use AI myself.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Turn these notes into a thread. Show me the draft first, then stage part 1 so I can check it before anything is public.
Which of my posts this month worked, ranked by engagement against views rather than raw likes?
Read every reply I got today and tell me which ones deserve an answer.
Publish these 6 screenshots as a carousel with alt text on each.
How much of today's posting quota have I used?
Where are my followers, by country?

The second one shows why this is useful. Threads reports views next to likes, replies, reposts and quotes, so a post's engagement can be measured against its reach. Ranked by raw likes, your best post is usually just your oldest.

It works well next to my Bluesky MCP server and Mastodon MCP server, so your AI can post the same update to Bluesky and share it on Mastodon in the same chat. Every server I've made is on my MCP servers page.

For the posts themselves, my free Threads character counter and Threads post analyzer help too.

How to install the Threads MCP server

Pick your app in the box at the top of this page. You log in once in a terminal, then add the server to your app with a single command or a pasted block. Nothing about your account goes in the app's config.

Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:

AppWhere the block goes
WindsurfIn the Cascade panel, open the Actions menu (…) and choose Open MCP config file, then paste the block.
ClineClick the MCP Servers icon in the Cline panel, open the Configure tab, click Configure MCP Servers, and paste the block.
ZedGo to Settings, then AI, then MCP Servers, and choose Add Server, then Add Local Server. Enter the block's command, arguments and variables, and Zed saves them under context_servers.
Before you start0/4

Set up your Threads account

Threads has no app passwords. You make a Meta app once, which takes about 10 minutes, and the login uses it to get a token for your profile.

Make your Meta app0/6

Watch out: The last step is the one people miss. Without it, every call comes back empty and nothing says why.

The callback address is your own computer, and it never leaves it. If port 8788 is taken, run the login with --port=9000 and add that address instead.

Log in

With the app ID and secret set, the login opens Meta's sign-in page, catches the answer and stores a 60-day token at ~/.threads-mcp/tokens.json:

export THREADS_APP_ID=your-app-id
export THREADS_APP_SECRET=your-app-secret
npx -y @thenavidm/threads-mcp-cli login

If your browser can't open, login --manual prints the address and takes a pasted token instead.

Search and profile lookups need Meta's review

The login asks for everything a tester gets with no review: posting, replies, insights and deleting. Searching other people's posts, looking up other profiles and tagging a location need Meta's App Review first. Once you have it, log in with --all-scopes.

Without the search permission, Meta doesn't refuse a search. It quietly narrows it to your own posts, and search_keyword tells you when that happens.

Keep your token alive

A Threads token lasts 60 days, and once it runs out, the only way back is logging in again. The server renews a token it stored itself during the last 20 days, whenever it runs.

The catch is that the server only runs while an app has it open. So if nothing uses it for 60 days, nothing renews it.

Pro tip: Run threads-cli refresh once a month, from a cron job or by hand, and the token never runs out. list_accounts and the doctor both show how many days each token has left.

A token you paste into THREADS_ACCESS_TOKEN can't be renewed, because the server has nowhere to write the new one. Tokens from Meta's Graph API Explorer are worse, since they stop working after an hour.

Check that it works

Run the doctor. It checks the network and your token, then checks each permission on its own, for posting, replies, insights, search and profile lookups, without posting anything, and names the permission to add for any that fail.

npx -y @thenavidm/threads-mcp-cli doctor

When it passes, restart your app and ask how much of today's posting quota you have left.

In Claude Code, /mcp also shows whether the Threads server is connected. It's one of the Claude Code commands worth knowing.

Use the Threads CLI

The CLI is the same 30 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script. Every tool name becomes a command with dashes, so create_post runs as threads-cli create-post.

npm install -g @thenavidm/threads-mcp-cli
threads-cli
threads-cli get-posts --limit 10
threads-cli get-top-posts --sample 25
threads-cli create-post --text "Shipped." --confirm

The bare threads-cli lists every command, threads-cli which <words> finds the command for a task, and threads-cli <command> --help shows what a command takes. Posting, replying, reposting and deleting need --confirm, the terminal's version of your approval.

threads-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.

These are the flags you'll use most:

FlagWhat it does
--jsonPrints JSON
--compactPrints the JSON on one line
--select a,b.cKeeps only those fields, and a dotted path goes deeper
--agentMachine mode: compact JSON, no prompts, and it never confirms anything
--confirmLets a write that asks first go ahead
--dry-runShows what a write would do, without doing it

A script can branch on the exit code:

Exit codeWhat it means
0It worked
1Something unexpected went wrong
2The command was typed wrong, or a write needed --confirm
3It wasn't found
4Threads rejected the token
5Threads failed or couldn't be reached
7You hit a rate limit, so wait and try again
10Nothing is set up yet, so run the login

MCP server or CLI: which one?

Both are the same program with the same 30 tools. The difference is when your AI pays for them, in the tokens it reads.

Every message, in an app that loads every tool
MCP server
11,400 tokens
CLI
Nothing
Every message, in Claude Code
MCP server
1,100 tokens
CLI
Nothing
When Threads comes up
MCP server
Nothing more, or in Claude Code the tools it picks
CLI
3,100 tokens, once
20 messages with Threads in one, every tool loaded
MCP server
227,000 tokens
CLI
3,100 tokens
Works in Claude Desktop's chat
MCP server
Yes
CLI
No, there's no terminal there
Works in a script, a cron job or CI
MCP server
No
CLI
Yes

An app that loads every tool up front sends the full list with every message, whether you mention Threads or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Threads comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 140 tokens.

When the whole conversation is about Threads, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

Where the MCP server's tokens go

Part of the tool listShare
JSON Schema structure, like types, required lists and nesting56%
Argument descriptions28%
Tool descriptions16%

56% of it is MCP writing every tool out as JSON Schema, which any server with this many tools pays. The rest is the wording that lets your AI use each tool without guessing.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't using Threads. In Claude Code that's the /mcp panel, and every AI app has its own switch. THREADS_READ_ONLY=1 cuts it to the 18 reading tools.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

Every Threads tool

The tables below list all 30 tools, grouped the way the repo groups them. Of these, 18 only read, and 12 change something on your profile.

Posting

create_post
What it does
Publish one post to Threads: creates the media container, waits for it to finish processing, then publishes.
Kind
Asks first
create_thread
What it does
Publish several posts as a thread, each replying to the one before.
Kind
Asks first
create_carousel
What it does
Publish 2 to 20 images or videos as one carousel post.
Kind
Asks first
stage_post
What it does
Build a media container without publishing.
Kind
Writes
publish_staged
What it does
Publish a container created by stage_post, waiting for processing first.
Kind
Asks first
get_container_status
What it does
The processing status of a container: IN_PROGRESS, FINISHED, ERROR or EXPIRED, with the failure reason when there is one.
Kind
Reads
quote_post
What it does
Publish a post that quotes an existing Threads post.
Kind
Asks first
repost
What it does
Repost an existing Threads post to your own profile.
Kind
Asks first
delete_post
What it does
Permanently delete one of your own Threads posts.
Kind
Asks first

Replies

reply_to
What it does
Publish a reply to a Threads post, yours or anyone's.
Kind
Asks first
get_replies
What it does
The direct replies to one post, one level deep.
Kind
Reads
get_conversation
What it does
Every reply under one of your posts, including replies to replies, flattened into one list with each reply naming its parent.
Kind
Reads
get_all_replies
What it does
Every reply you have received, newest first, across every post.
Kind
Reads
hide_reply
What it does
Hide a reply on one of your posts, or unhide one you hid.
Kind
Writes
get_pending_replies
What it does
Replies waiting for approval on posts published with enable_reply_approvals.
Kind
Reads
manage_pending_reply
What it does
Approve a reply waiting in the approval queue, making it public, or ignore it so it stays hidden.
Kind
Asks first

Reading posts

get_posts
What it does
Your own Threads posts, newest first, with ids and permalinks.
Kind
Reads
get_post
What it does
One Threads post by its numeric id, with its full field set: text, media, permalink, topic tag, link attachment, quoted post and whether it has replies.
Kind
Reads

Insights

get_post_insights
What it does
Views, likes, replies, reposts, quotes and shares for one of your posts.
Kind
Reads
get_account_insights
What it does
Profile-level views, likes, replies, reposts, quotes, link clicks and follower count.
Kind
Reads
get_follower_demographics
What it does
Follower breakdown by country, city, age or gender.
Kind
Reads
get_top_posts
What it does
Fetch recent posts, pull the metrics for each, and rank them.
Kind
Reads

Search and profiles

search_keyword
What it does
Search public Threads posts by keyword.
Kind
Reads
search_topic_tag
What it does
Public posts carrying a topic tag.
Kind
Reads
lookup_profile
What it does
A public Threads profile by username, with its follower count and seven-day totals for views, likes, quotes and reposts.
Kind
Reads
list_allowlisted_countries
What it does
The country codes this profile may restrict a post to.
Kind
Reads

Account and token

list_accounts
What it does
Every connected Threads profile, which one acts by default, and how many days each token has left before it expires.
Kind
Reads
whoami
What it does
Confirm which Threads profile the current token acts as, and return the live profile: username, name, bio, verification, and whether the profile is eligible for geo-gated posts.
Kind
Reads
get_publishing_limit
What it does
How much of the rolling 24-hour quota this profile has spent.
Kind
Reads
refresh_token
What it does
Refresh the long-lived access token, giving it another 60 days.
Kind
Writes

Is the Threads MCP server safe?

A post is public the moment it lands, and Threads has no edit. Fixing a typo means deleting and posting again, which loses the replies and likes on the original. So nine tools ask first. They're the ones marked "Asks first" in the tool tables above.

When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:

  • Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
  • An app that can show forms asks you in a form.
  • Any other app takes your AI's confirm: true as the yes, so tell your AI to check with you first.
  • An agent with no person to ask needs THREADS_CONFIRM=model, so its confirm: true counts in every app.
  • In a terminal, you add --confirm to the command.

If the answer is no, nothing reaches Threads.

Hiding a reply doesn't ask, because it's one call to undo. Asking on every hide would only train your AI to pass the check without thinking.

Stage a post before it goes out

stage_post builds a post and stops, so nothing is public yet. It holds for 24 hours, and publish_staged puts it live when you're happy with it.

Make it read-only

Set THREADS_READ_ONLY=1 and every write disappears from the tool list, leaving 18 reading tools. Your AI can't call a tool it can't see.

THREADS_ALLOW_DESTRUCTIVE=0 is the middle setting. Hiding replies and renewing the token still work, and posting, replying and deleting don't.

Keep a log of every write

Set THREADS_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Watch out: Replies and search results are text other people wrote, and a reply can try to give your AI orders. The server tells your AI to treat it as data, but THREADS_READ_ONLY=1 is the real defense for an agent working through other people's replies.

Threads' daily limits

Meta limits each profile over a rolling 24 hours: 250 posts, 1,000 replies, 100 deletes, 2,200 searches and 1,000 profile lookups. get_publishing_limit shows what's left today.

Your data

Nothing goes anywhere but Meta's Threads API. Your token is stored in ~/.threads-mcp/tokens.json, readable only by your user account, and there's no tracking of any kind.

To disconnect, remove the app in the Threads app under Settings, then Website permissions. That cuts access right away.

Threads MCP server settings

Every setting is an environment variable, in your app's config or your shell.

THREADS_APP_ID
Default
none
What it does
Holds your Meta app's ID, which only the login needs
THREADS_APP_SECRET
Default
none
What it does
Holds your Meta app's secret, which only the login needs
THREADS_ACCESS_TOKEN
Default
none
What it does
Holds a token you paste in, which the server can't renew
THREADS_ACCOUNTS
Default
none
What it does
Lists several profiles, as JSON
THREADS_DEFAULT_ACCOUNT
Default
the first one
What it does
Picks the profile that acts when a tool names none
THREADS_TOKEN_STORE
Default
~/.threads-mcp/tokens.json
What it does
Sets where the login keeps tokens
THREADS_REFRESH_WINDOW_DAYS
Default
20
What it does
Sets how many days before it runs out a token is renewed
THREADS_READ_ONLY
Default
0
What it does
1 hides every write
THREADS_ALLOW_DESTRUCTIVE
Default
1
What it does
0 blocks posting, replying and deleting
THREADS_AUDIT_LOG
Default
none
What it does
Logs every attempted write to a file
THREADS_USER_ID
Default
none
What it does
Its numeric profile id. Resolved from the token when absent
THREADS_USERNAME
Default
none
What it does
Its username, for matching and display. Also resolved
THREADS_PERSIST_TOKENS
Default
none
What it does
0 stops writing refreshed tokens back to the store
THREADS_CONTAINER_TIMEOUT_MS
Default
120000
What it does
How long to wait for media to process
THREADS_REQUEST_TIMEOUT_MS
Default
30000
What it does
Per-request deadline
THREADS_MIN_REQUEST_INTERVAL_MS
Default
120
What it does
Spacing between requests
THREADS_MAX_RETRIES
Default
3
What it does
Retries on 5xx and quota codes
THREADS_GRAPH_HOST
Default
graph.threads.net
What it does
The Graph host
THREADS_USER_AGENT
Default
threads-mcp
What it does
The User-Agent sent to Meta
THREADS_SURFACE
Default
full
What it does
search lists three tools that find, describe and run the rest
THREADS_TOOL_TIMEOUT_MS
Default
none
What it does
Gives up on any tool after this many milliseconds
THREADS_CONFIRM
Default
human
What it does
model lets your AI's confirm: true approve on its own, for an agent with no person to ask
THREADS_HTTP_PORT
Default
8787
What it does
Sets the port for --http
THREADS_HTTP_HOST
Default
127.0.0.1
What it does
Sets the address for --http, and any other needs a token
THREADS_HTTP_TOKEN
Default
none
What it does
Sets the bearer token every --http request needs
THREADS_HTTP_ALLOWED_ORIGINS
Default
none
What it does
Lists other websites allowed to call --http, comma separated
THREADS_DEBUG
Default
off
What it does
1 prints debug lines

Troubleshooting

Run the doctor first. It tests each permission on its own and names the fix.

What you seeWhat to do
Every call comes back emptyAdd yourself as a Threads Tester on your app, and accept the invite
"Threads rejected the token"It ran out, or it came from the Graph API Explorer. Run the login again
It stopped working about 2 months inThe 60-day token ran out. Run the login again, then renew it monthly
Search only finds your own postsMeta hasn't approved the search permission for your app yet
A media error a few minutes after postingThe image or video link has to be public HTTPS and can't redirect to a login page
"…so it will not run without confirm: true"That's the safety check working. Approve it when your app asks, or say you want it posted
Rate limitedYou hit a daily limit. get_publishing_limit shows what's left

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

More free Threads tools

Check a post's length before your AI sends it, or turn a post into an image to share.

FAQs about the Threads MCP server & CLI

Here are the questions people ask most about the Threads MCP server and CLI.

The Threads MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor act on your Threads profile.

It has 30 tools for posting, threads, carousels, replies, insights and search, and the same tools run as a CLI that agents like Claude Code and Codex use, or that you type yourself.

An MCP server is a standard way to give an AI app real access to a tool, so it can act instead of guessing.

MCP stands for Model Context Protocol, and Claude, Codex, Cursor and many other AI apps speak it.

The Threads CLI is the same program as the Threads MCP server, run as commands.

AI agents like Claude Code, Codex and OpenCode run them for you, and you can type them in a terminal or a script.

Every tool is a command with dashes, so create_post runs as threads-cli create-post, and one npm package installs both.

Use the Threads MCP server in an AI app with no terminal, like Claude Desktop's chat, and the CLI in a terminal, a script or a cron job.

In an AI app that can run commands, like Claude Code, Codex or Cursor, the CLI is the lighter choice, because it costs nothing until it runs.

Yes, the Threads MCP server is free and open source under the MIT license.

Meta's Threads API is free too, so the only thing you pay for is your own AI app.

Yes, the Threads MCP server needs a Meta app with the Threads API, because Threads has no app passwords.

Making one takes about 10 minutes, and you only do it once.

The Threads MCP server returns nothing when your profile isn't a Threads Tester on your own Meta app.

Add yourself under Roles, then accept the invite in the Threads app under Settings, Website permissions, Invites.

A Threads token lasts 60 days.

The Threads MCP server renews a token it stored during the last 20 days whenever it runs, so running threads-cli refresh once a month keeps it alive for good.

The Threads MCP server posts when you ask it to.

Posting, replying, reposting and deleting wait for your approval in an app that can ask, like Claude Code, and stage_post lets you check a post before it goes public.

The Threads MCP server works with any app that speaks MCP.

That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes.

Yes, the Threads MCP server connects as many profiles as you log in.

Every tool that acts as you takes an optional account, and a default decides which profile acts when you don't say.

I did.

I'm Navid Moazzez, and I made the Threads MCP server & CLI as one of my free tools on navid.me.

You can read more about me.

The code is on GitHub under the MIT license, and the package is on npm.

More MCP servers & CLIs

Related free tools

Navid Moazzez

AI business strategist & AI OS builder

Navid Moazzez helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life.

Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Read the affiliate disclaimer.

Free AI newsletter

The most actionable AI newsletter for founders

Every week, get proven AI strategies, curated tools, and step-by-step systems to grow your audience, create better content, and build a profitable creator business.

No fluff, no filler, no BS. Just five minutes each week that might level up your online business and life.

P.S. Sign up now to get free access to my ultimate AI tools guide for creators.

Loved by 10,000+ readers
Loved by 10,000+ readers