# Thread Storm

MCP server for publishing threads to Threads and Twitter/X simultaneously from Claude Code. Journal your thoughts, convert them to viral threads, and post everywhere at once.

## Features

13 tools available via MCP:

### Threads (9 tools)
| Tool | Description |
|------|-------------|
| `threads_get_profile` | Fetch Threads profile info |
| `threads_get_posts` | List recent posts with pagination |
| `threads_get_post_details` | Get full details for a specific post |
| `threads_get_post_insights` | Engagement metrics (views, likes, replies, reposts, quotes, shares) |
| `threads_get_replies` | Direct replies to a specific post |
| `threads_search` | Keyword search across Threads |
| `threads_get_account_insights` | Account-level metrics |
| `threads_publish_text` | Publish a text post (optional reply) |
| `threads_publish_thread` | Publish a multi-post thread |

### Twitter/X (3 tools)
| Tool | Description |
|------|-------------|
| `twitter_get_profile` | Fetch Twitter profile info |
| `twitter_publish_text` | Post a tweet (optional reply) |
| `twitter_publish_thread` | Post a tweet thread |

### Cross-Platform (1 tool)
| Tool | Description |
|------|-------------|
| `storm_publish_thread` | Publish to BOTH Threads and Twitter simultaneously |

## Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- A Meta developer app with Threads API access
- A Twitter/X developer app with Read+Write permissions

## Quick Start

1. Clone the repo:
   ```bash
   git clone https://github.com/asadhuddleduck/thread-storm.git
   cd thread-storm
   ```

2. Install dependencies:
   ```bash
   uv sync
   ```

3. Add to your `.mcp.json`:
   ```json
   {
     "mcpServers": {
       "thread-storm": {
         "command": "uv",
         "args": ["run", "--python", "3.12", "--directory", "/path/to/thread-storm", "thread-storm"],
         "env": {
           "THREADS_ACCESS_TOKEN": "your-threads-token",
           "THREADS_APP_SECRET": "your-threads-app-secret",
           "TWITTER_API_KEY": "your-twitter-api-key",
           "TWITTER_API_SECRET": "your-twitter-api-secret",
           "TWITTER_ACCESS_TOKEN": "your-twitter-access-token",
           "TWITTER_ACCESS_TOKEN_SECRET": "your-twitter-access-token-secret"
         }
       }
     }
   }
   ```

4. Restart Claude Code. All 13 tools will be available.

## Environment Variables

| Variable | Platform | Description |
|----------|----------|-------------|
| `THREADS_ACCESS_TOKEN` | Threads | Long-lived token from Meta's User Token Generator |
| `THREADS_APP_SECRET` | Threads | App secret from Meta developer app |
| `TWITTER_API_KEY` | Twitter | OAuth 1.0a consumer API key |
| `TWITTER_API_SECRET` | Twitter | OAuth 1.0a consumer API secret |
| `TWITTER_ACCESS_TOKEN` | Twitter | OAuth 1.0a user access token |
| `TWITTER_ACCESS_TOKEN_SECRET` | Twitter | OAuth 1.0a user access token secret |

## Architecture

```
src/thread_storm/
  threads_client.py   — Threads HTTP client (GET via urllib, POST via curl)
  twitter_client.py   — Twitter client via tweepy (OAuth 1.0a)
  server.py           — FastMCP server with 13 tool definitions
```

### Threads Publishing Flow
1. Create media container (POST)
2. Poll container status until FINISHED (2s intervals)
3. Publish container (POST)
4. Wait 10s propagation delay before next reply

### Twitter Publishing Flow
1. Post tweet (POST /2/tweets)
2. Post next tweet with `in_reply_to_tweet_id`
3. No polling or delays needed

### storm_publish_thread
Runs both platforms in parallel using `ThreadPoolExecutor`. Twitter finishes in seconds while Threads takes 1-2 minutes for a 9-post thread.

## Token Management (Threads)

Threads tokens expire after 60 days. Auto-refresh kicks in at day 30:
1. Token saved to `~/.threads-mcp/token.json` on first use
2. After day 30, exchanged for a fresh 60-day token
3. New token saved to both `token.json` and `.mcp.json`

Twitter OAuth 1.0a tokens do not expire.

## Rate Limits

- **Threads publishing:** 250 posts per 24 hours
- **Threads search:** 500 queries per 7 days
- **Twitter publishing:** 500 tweets per month (Free tier)

## License

MIT