Threads MCP

An MCP server that gives Claude (or any MCP client) access to Threads through your own logged-in browser. Search posts by keyword and get the top results with their likes, replies and reposts, read your feed, profiles and replies, work with your DMs, and draft posts, all from your AI assistant.

Everything runs on your machine. There is no Meta developer app, no API key, and no third-party server: the tool drives a dedicated Chrome profile that only you log in to.

Independent open-source project, not affiliated with Meta or Threads. Threads is a trademark of Meta Platforms, used here only to identify the service this software works with. Automated use of Threads may conflict with its terms; use it at a low, personal volume and at your own risk.

What you can do

Post-returning tools (search_posts, get_feed, get_user_posts, get_post replies) default to format="compact": text trimmed to 280 characters and ids and media links left out, about a third smaller than format="full", which returns every field. Exports always contain full data.

With format="full", every post comes back with the same fields: url, author (username, name, verified), text, created_at (UTC), likes, replies, reposts, quotes, score, media_type, media_urls, is_reply. The score is likes + 2 x replies + 3 x reposts + 2 x quotes.

Requirements

• macOS, Linux or Windows
• uv
• Google Chrome (recommended). Without it, run uvx --from git+https://github.com/sunnycho100/threads-mcp patchright install chromium once and the server uses Chromium instead.
• A Threads account

Setup

1. Log in once

uvx threads-mcp@latest --login

@latest installs from PyPI and picks up fixes automatically, which matters because Threads changes its pages from time to time. To run the newest unreleased code instead, use uvx --from git+https://github.com/sunnycho100/threads-mcp threads-mcp wherever this README says uvx threads-mcp@latest.

A Chrome window opens on threads.com. Log in (Instagram login works) and the window closes by itself. The session is saved in ~/.threads-mcp/profile, separate from your everyday Chrome.

Check it:

uvx threads-mcp@latest --status

logged in as @your_username
profile: /Users/you/.threads-mcp/profile

2. Add it to your MCP client

Claude Code

claude mcp add threads -- uvx threads-mcp@latest

Or, inside a clone of this repo, the included .mcp.json registers the server automatically.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows)

{
  "mcpServers": {
    "threads": {
      "command": "uvx",
      "args": ["threads-mcp@latest"],
      "env": { "UV_HTTP_TIMEOUT": "300" }
    }
  }
}

Cursor, Windsurf and other clients use the same command and args in their MCP settings.

Claude Desktop, one-click bundle

git clone https://github.com/sunnycho100/threads-mcp && cd threads-mcp
npx @anthropic-ai/mcpb pack . threads-mcp.mcpb

Open threads-mcp.mcpb with Claude Desktop (double-click, or Settings > Extensions > Install Extension). The install dialog offers a read-only toggle. Run --login once in a terminal first, as above.

Docker

Log in from inside the container with the built-in viewer:

docker build -t threads-mcp https://github.com/sunnycho100/threads-mcp.git
docker run --rm -it -p 127.0.0.1:6080:6080 -v ~/.threads-mcp-docker:/data threads-mcp --login-viewer

Open the printed http://localhost:6080/vnc.html, enter the one-time password it prints, and log in to Threads in the window that appears. The container exits once the session is saved. The viewer listens on localhost only.

Or log in on your computer and move the session in:

uvx --from git+https://github.com/sunnycho100/threads-mcp threads-mcp --export-session ~/threads-session.json
docker run --rm -v ~/.threads-mcp-docker:/data -v ~/threads-session.json:/session.json:ro threads-mcp --import-session /session.json
rm ~/threads-session.json

The exported file holds your login cookies and is created readable only by you; delete it after importing. Then point your client at the container:

{
  "mcpServers": {
    "threads": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/Users/you/.threads-mcp-docker:/data", "threads-mcp"]
    }
  }
}

Restart the client, then ask something like "search Threads for posts about rust async and show me the top 10".

Examples

Ask in plain language; the assistant picks the tool. The calls below show what it sends.

Top posts for a keyword

search_posts(query="rust async", limit=10)

{
  "query": "rust async", "sort": "top", "count": 10,
  "results": [
    {"url": "https://www.threads.com/@someone/post/DZ6Wq...", "author": {"username": "someone", "full_name": "Some One", "verified": false},
     "text": "...", "created_at": "2026-06-23T02:33:30Z", "likes": 2692, "replies": 334, "reposts": 377, "quotes": 12, "score": 4848,
     "media_type": "image", "media_urls": ["..."], "is_reply": false}
  ]
}

Only popular posts from the last week, saved to a spreadsheet

search_posts(query="indie hacker", min_likes=100, since_days=7, limit=30, export="csv")

The response includes export_path, for example ~/.threads-mcp/exports/search-indie-hacker-20261011-091500.csv. CSV and Markdown files are UTF-8, so Korean, Japanese and emoji come through intact.

Newest posts first

search_posts(query="rust async", sort="recent", limit=20)

What works for a topic

keyword_insights(query="vibe coding", limit=50)

Returns engagement medians, the authors with the most total engagement, the hours (your local time) when the best-performing posts went up, and the media mix.

Who to follow on a topic

search_profiles(query="ios developer", sort="followers", limit=10)

A post and its replies

get_post(url="https://www.threads.com/@someone/post/DZ6WqOxlC-t", reply_limit=20)

DMs

list_conversations()
get_conversation(username="friend_name", limit=20)

Writing, with a confirmation step

create_post(text="Shipping a new side project today")

{"confirm_required": true, "preview": {"action": "create_post", "text": "Shipping a new side project today", "length": 33},
 "note": "Show this preview to the user and call again with confirm=true to proceed."}

Nothing is posted until the assistant shows you the preview and calls again with confirm=true. The same applies to send_message and reply_to_post.

Usernames are accepted as name, @name or a profile URL. Post links work with threads.com or threads.net.

How it works

Threads' web app ships its data as JSON: posts and profiles are embedded in each page, and more arrive through the page's own GraphQL requests as you scroll. The server opens the page in your logged-in profile, collects that JSON, and picks out anything shaped like a post or a user, wherever it sits. It does not replay Meta's internal API calls; it reads what the page itself loads, the way you would by scrolling.

DMs are loaded over a live connection rather than page JSON, so the DM tools read the rendered conversation instead. Posting and replying use the normal composer.

MCP client --stdio--> server.py      tools, confirmations, error messages
                        service.py   search, feed, profiles, posts
                        session.py   one Chrome profile, one page, one task at a time
                        extract.py   finds posts and users in the page JSON
                        ranking.py   score, sort, filter, insights, export
                        dm.py        inbox and conversations
                        compose.py   new posts and replies

Safety

• Writes need confirmation. send_message, create_post and reply_to_post return a preview and do nothing until called again with confirm=true.
• Human pace. Scrolls and typing use randomized delays, and only one browser task runs at a time, even when the client calls tools in parallel.
• Low volume. Every list is capped at 100 items, and a call is a few page loads, not a crawl.
• Account checks. If Threads shows a checkpoint or account warning, the server stops all browser activity and tells you to resolve it in the app.
• No social actions. There are no tools for likes, follows, reposts or deletes.
• Local data. The browser profile and exports live in ~/.threads-mcp. Nothing is sent anywhere except threads.com.

Command line

threads-mcp               run the MCP server over stdio (what clients launch)
threads-mcp --login       open a browser window and sign in
threads-mcp --status      show the logged-in account (exit code 1 if not logged in)
threads-mcp --logout      delete the saved browser profile
threads-mcp --export-session FILE   save the login cookies (owner-only file) for Docker or another machine
threads-mcp --import-session FILE   load cookies saved by --export-session
threads-mcp --no-headless run the server with the browser window visible
threads-mcp --version

Options for the server and login:

Environment variables:

The browser closes itself after 10 idle minutes and reopens on the next call.

Troubleshooting

Development

git clone https://github.com/sunnycho100/threads-mcp
cd threads-mcp
uv sync
uv run pytest -q              # unit tests, no browser needed
uv run threads-mcp --login    # once
uv run python scripts/e2e.py  # every tool against your live account

• Unit tests run against scrubbed fixtures captured from real pages (tests/fixtures/). scripts/scrub_fixture.py turns a raw capture into a fixture, replacing usernames, names, bios, captions and media links.
• scripts/e2e.py starts the server over stdio with the MCP client and calls every tool. Writes run in dry-run mode: the composer is opened, filled, checked and cancelled. Put your own test keywords in .local/keywords.txt (gitignored, one per line); they are never written to the report. The latest results are in docs/E2E_REPORT.md.
• Releasing: uv run python scripts/bump_version.py X.Y.Z, commit, then push a vX.Y.Z tag. The release workflow tests, builds and publishes to PyPI through trusted publishing.
• Design notes: docs/superpowers/specs/2026-10-11-threads-mcp-design.md.
• How this compares with linkedin-mcp-server, including what is not built yet: docs/LINKEDIN_PARITY.md.

Acknowledgements

The browser-session approach follows stickerdaniel/linkedin-mcp-server, and reading the page's own JSON follows xpzouying/xiaohongshu-mcp.