# Open Threads 🧵

> **Your own Meta Threads account for AI agents: headless CLI, MCP server, and local API.**

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)

Open Threads is an open-source bridge that connects your signed-in [Meta Threads](https://www.threads.net/) account to autonomous AI agents (such as **Claude Code**, **Codex**, **Cursor**, **Antigravity**, and **OpenCode**). 

By providing a **headless CLI**, an **MCP Server**, and a **local REST API**, it empowers AI agents to browse feeds, scrape user profiles, analyze discussion topics, check pinned posts, publish new threads, attach media, reply, like, repost, and bookmark without needing a graphical user interface.

---

## 🌟 Key Capabilities

- **🔐 Zero-Credential-Exposure Authentication**: Log in once using a normal, visible browser session. Your cookies and profile are stored safely in `~/.open-threads/chrome-profile` on your machine.
- **🤖 Built for AI Agents**: Native Model Context Protocol (MCP) server so coding agents can invoke Threads tools directly from chat.
- **📄 Complete Profile & Pinned Post Scraping**: Extract display names, handles, bios, follower counts, verified badges, avatars, profile links, and pinned threads.
- **🧵 Full Thread & Reply Tree Inspection**: Retrieve complete discussion threads, timestamps, view counts, like/reply/repost statistics, and nested replies.
- **🔎 Topic & Community Search**: Discover discussions in communities (e.g. `#study`, `#tech`, `#ai`), with sorting by **Top** or **Recent**.
- **✍️ Publishing & Interactions**:
  - Publish threads with text and image/video uploads.
  - Reply to any thread post.
  - React/like or unlike posts.
  - Repost or quote repost.
  - Save / bookmark posts.
  - Follow or unfollow profiles.
- **⚡ Background Daemon & Job Queue**: Run `open-threads serve` to maintain a persistent browser instance with sub-second command response times.

---

## 🏗️ Architecture

```
+-------------------------------------------------------------+
|                     AI Coding Agents                        |
|       (Claude Code / Codex / Antigravity / Cursor)          |
+-------------------------------------------------------------+
               |                               |
       MCP (stdio)                        CLI (--json)
               |                               |
               v                               v
+-------------------------------------------------------------+
|                        open-threads                         |
|  - bin/cli.js (CLI entry point)                             |
|  - src/tools.js (MCP Server: @modelcontextprotocol/sdk)    |
|  - src/server.js (Local REST API & Background Job Queue)    |
|  - src/threads.js (Playwright / Chrome Driver & Parser)     |
+-------------------------------------------------------------+
                               |
                   CDP (127.0.0.1:9345)
                               v
+-------------------------------------------------------------+
|             Google Chrome (Persistent Profile)              |
|               ~/.open-threads/chrome-profile/               |
+-------------------------------------------------------------+
                               |
                               v
                       https://threads.net/
```

---

## 🚀 Quick Start

### 1. Installation

Clone and install dependencies:

```bash
git clone https://github.com/mkshaonexe/open-threads.git
cd open-threads
npm install
```

### 2. Initial Sign-in

Launch the sign-in window:

```bash
node bin/cli.js login
```

A visible Chrome window opens to `https://www.threads.net/login`. Log in using your Instagram / Threads credentials, security key, or QR code. Once signed in, Open Threads detects your authenticated state and closes the window. All future commands run headlessly.

Verify your session:

```bash
node bin/cli.js status
```

---

## 💻 CLI Usage

All CLI commands support the `--json` flag for machine-readable output.

### Browsing & Feeds

```bash
# Fetch Home "For You" feed (default 10 posts)
node bin/cli.js feed --limit 10

# Fetch "Following" feed
node bin/cli.js feed --filter following --limit 15 --json
```

### Profile & Pinned Posts

```bash
# Fetch profile, bio, follower count, avatar, and pinned post
node bin/cli.js profile meta --json

# Fetch a user's recent threads
node bin/cli.js user-posts meta --limit 10

# Fetch a user's uploaded media
node bin/cli.js user-posts meta --tab media --limit 5
```

### Inspecting Specific Posts

```bash
# View post details, view count, author, and thread replies
node bin/cli.js post DfX2w6Tndjo --json

# You can also pass the full URL
node bin/cli.js post "https://www.threads.net/@meta/post/DfX2w6Tndjo"
```

### Communities, Topics & Search

```bash
# Explore study-related topics and communities
node bin/cli.js topic "study" --sort top --limit 10 --json

# Explore recent posts in a topic
node bin/cli.js topic "technology" --sort recent --limit 10

# Search posts by keyword
node bin/cli.js search "artificial intelligence" --type top --limit 10

# Search user accounts by name or handle
node bin/cli.js search "google" --type user --limit 10
```

### Creating Posts & Interactions

```bash
# Publish a new thread
node bin/cli.js create "Hello from Open Threads CLI! 🚀"

# Publish with images or videos
node bin/cli.js create "Check out this visual architecture!" --media ./docs/architecture.png

# Reply to a thread post
node bin/cli.js reply DfX2w6Tndjo "This is very informative, thank you!"

# Like a post
node bin/cli.js like DfX2w6Tndjo

# Unlike a post
node bin/cli.js like DfX2w6Tndjo --unlike

# Repost a thread
node bin/cli.js repost DfX2w6Tndjo

# Quote a thread
node bin/cli.js repost DfX2w6Tndjo --quote "Fascinating update from the team!"

# Bookmark / save a post
node bin/cli.js save DfX2w6Tndjo

# Follow a user
node bin/cli.js follow meta
```

---

## 🤖 MCP Server Setup for AI Agents

To connect Open Threads to your AI coding agents, add the server configuration:

### Configuration (`mcp.json` / Claude Desktop / Antigravity)

```json
{
  "mcpServers": {
    "open-threads": {
      "command": "node",
      "args": ["/absolute/path/to/open-threads/bin/cli.js", "mcp"]
    }
  }
}
```

### Available MCP Tools

- `threads_status`: Check active sign-in status and account details.
- `threads_feed`: Fetch home feed (`for_you` or `following`).
- `threads_profile`: Retrieve user profile, bio, follower count, avatar, and pinned post.
- `threads_user_posts`: Fetch timeline posts, replies, media, or reposts.
- `threads_post`: Retrieve post detail with metrics and thread replies.
- `threads_create_post`: Publish a thread with optional image/video files.
- `threads_reply`: Reply to an existing thread.
- `threads_like`: Like or unlike a post.
- `threads_repost`: Repost or quote a post.
- `threads_save`: Bookmark or unsave a post.
- `threads_delete_post`: Delete a user-owned post (`confirm: true`).
- `threads_search`: Search posts or user accounts.
- `threads_topic`: Explore community topics / hashtags.
- `threads_follow`: Follow or unfollow a profile.
- `threads_download`: Download photo/video media to local storage.

---

## ⚡ Background HTTP Server & Daemon

To keep a single browser session warm for instant responses, start the local server:

```bash
node bin/cli.js serve --port 2795
```

When running, the server listens strictly on `http://127.0.0.1:2795` and secures all calls with a local bearer token.

Print your local API key:

```bash
node bin/cli.js key
```

---

## 📁 Repository Structure

```
open-threads/
├── bin/
│   └── cli.js                  # CLI executable and MCP stdio launcher
├── src/
│   ├── chrome.js               # Chrome lifecycle and CDP lock manager
│   ├── client.js               # Client for local HTTP daemon
│   ├── config.js               # Configuration and path resolution
│   ├── errors.js               # Standardized error definitions
│   ├── schema.js               # Zod validation schemas and method dictionary
│   ├── server.js               # Local loopback HTTP REST server and job queue
│   ├── threads.js              # Playwright automation driver and parser
│   └── tools.js                # Model Context Protocol (MCP) server
├── skills/
│   └── open-threads/
│       └── SKILL.md            # Agent Skill specification
├── test/
│   ├── config.test.js          # Config unit tests
│   ├── mcp.test.js             # MCP tools unit tests
│   └── schema.test.js          # Schema and validation unit tests
├── AGENTS.md                   # AI Agent guidance rules
├── LICENSE                     # MIT License
├── package.json
└── README.md                   # Complete documentation
```

---

## 🛡️ Ethical Usage & Security Disclosure

Open Threads is designed for personal productivity, agent-assisted automation, ethical testing, and research under user authorization. It operates on your own authenticated web session without attempting to bypass platform protections or access control mechanisms. 

- Always adhere to [Meta's Terms of Service](https://help.instagram.com/581066165581870) and community standards.
- Respect rate limits and avoid spammy or high-frequency automated behavior.
- Never store or commit private credentials, browser profiles, or cookies to public repositories.

---

## 📄 License

[MIT](LICENSE) © 2026 mkshaonexe