{"id":"7db244bb-c604-4e17-9c72-9c68b964a9aa","slug":"threads-mcp","kind":"mcp","name":"threads-mcp","summary":"Production-ready Model Context Protocol server for Threads.com API. Features rate limiting, caching, webhooks, and full TypeScript support. Integrate Threads with Claude, ChatGPT, and AI assistants. 9","owner":"quinnjr","repoUrl":"https://github.com/quinnjr/threads-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":18,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-12-15T18:48:27.000Z","addedAt":"2026-10-14T05:19:32.738Z","logoUrl":"https://avatars.githubusercontent.com/u/423821?u=ee74e1a07bc8021df41234190cc20537836c2713&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","memory-knowledge","cloud-infra"],"tags":["ai","api-client","caching","chatgpt","claude","rate-limiting","sdk","threads"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T22:49:09.688Z","sample":false,"url":"https://conduits.dev/tools/threads-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"@pegasusheavy/threads-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Threads MCP Server\n\nA powerful Model Context Protocol (MCP) server for integrating with the Threads.com API. This server provides comprehensive tools for creating, reading, and managing Threads content programmatically.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)\n[![Node](https://img.shields.io/badge/Node-%3E%3D18.0.0-green.svg)](https://nodejs.org/)\n[![Test Coverage](https://img.shields.io/badge/coverage-%3E90%25-brightgreen.svg)](https://vitest.dev/)\n\n🌐 **[Visit the Website](https://pegasusheavyindustries.github.io/threads-mcp/)** for a better reading experience!\n\n## Features\n\n- 🚀 **Complete Threads API Integration** - Full support for Threads.com API v1.0\n- 🔧 **MCP Protocol** - Standard Model Context Protocol implementation\n- 📊 **Analytics & Insights** - Access engagement metrics and analytics\n- 💬 **Conversation Management** - Create threads, replies, and manage conversations\n- 🎯 **Type-Safe** - Full TypeScript support with Zod schema validation\n- ⚡ **Rate Limiting** - Token bucket algorithm to prevent API rate limit violations\n- 💾 **Caching Layer** - In-memory caching with TTL and LRU eviction\n- 🔔 **Webhook Support** - Event-based webhooks with automatic retries and signature verification\n- ✅ **Well Tested** - >90% test coverage with Vitest\n- 🔄 **Modern Stack** - Built with latest npm packages and best practices\n\n## Available Tools\n\nThe server provides the following MCP tools:\n\n### Profile & Content Management\n\n- **`threads_get_profile`** - Get authenticated user's profile information\n- **`threads_get_threads`** - Retrieve user's threads (posts) with pagination\n- **`threads_get_thread`** - Get a specific thread by ID\n- **`threads_create_thread`** - Create new threads with text, images, or videos\n- **`threads_reply_to_thread`** - Reply to existing threads\n\n### Engagement & Analytics\n\n- **`threads_get_insights`** - Get analytics for threads or user account\n- **`threads_get_replies`** - Retrieve replies to a specific thread\n- **`threads_get_conversation`** - Get full conversation threads\n\n## Prerequisites\n\nBefore you begin, you'll need:\n\n1. **Node.js 18+** - [Download here](https://nodejs.org/)\n2. **pnpm** - Install with `npm install -g pnpm`\n3. **Meta Developer Account** - [Sign up here](https://developers.facebook.com/)\n4. **Threads Account** - Your personal Threads account\n5. **OAuth 2.0 Credentials** - See [OAuth Setup Guide](docs/OAUTH_SETUP.md)\n\n### Getting Your Threads API Credentials\n\n**⚠️ Important**: Threads uses OAuth 2.0 authentication. You cannot use simple API keys.\n\n#### Quick Setup (Automatic OAuth)\n\n1. **Create a Meta App**\n   - Visit [Meta for Developers](https://developers.facebook.com/)\n   - Create a new app and add the Threads API product\n   - Add OAuth redirect URI: `http://localhost:48810/callback`\n   - Get your **App ID** and **App Secret**\n\n2. **Configure Claude Desktop**\n   - Add to your Claude Desktop config with just your App ID and Secret\n   - The server will automatically handle OAuth on first run\n   - A browser will open for you to authorize the app\n   - Tokens are stored and automatically refreshed!\n\nThat's it! No manual OAuth flow needed. 🎉\n\n📖 **For detailed instructions**, see the [OAuth Setup Guide](docs/OAUTH_SETUP.md)\n\n## Installation\n\n### From npm (when published)\n\n```bash\npnpm install -g threads-mcp\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/PegasusHeavyIndustries/threads-mcp.git\ncd threads-mcp\n\n# Install dependencies\npnpm install\n\n# Build the project\npnpm run build\n```\n\n## Configuration\n\n### Automatic OAuth (Recommended)\n\nThe simplest way is to let the server handle OAuth automatically:\n\n**For Claude Desktop**, edit your config file:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"threads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@pegasusheavy/threads-mcp\"],\n      \"env\": {\n        \"THREADS_APP_ID\": \"your-app-id\",\n        \"THREADS_APP_SECRET\": \"your-app-secret\"\n      }\n    }\n  }\n}\n```\n\nWhen you start Claude Desktop:\n\n1. A browser will automatically open\n2. Log in and authorize the app\n3. Done! Tokens are stored and auto-refreshed\n\n### Manual Token (Legacy)\n\nIf you prefer to use pre-generated tokens:\n\n```json\n{\n  \"mcpServers\": {\n    \"threads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@pegasusheavy/threads-mcp\"],\n      \"env\": {\n        \"THREADS_ACCESS_TOKEN\": \"your-long-lived-token\",\n        \"THREADS_USER_ID\": \"your-user-id\"\n      }\n    }\n  }\n}\n```\n\nSee [OAuth Setup Guide](docs/OAUTH_SETUP.md) for manual OAuth flow instructions.\n\n## Usage\n\n### Running the Server\n\n```bash\n# If installed globally\nthreads-mcp\n\n# If running from source\npnpm run dev\n```\n\n### Using with MCP Clients\n\nConfigure your MCP client (like Claude Desktop) to use this server:\n\n```json\n{\n  \"mcpServers\": {\n    \"threads\": {\n      \"command\": \"threads-mcp\",\n      \"env\": {\n        \"THREADS_ACCESS_TOKEN\": \"your-access-token\",\n        \"THREADS_USER_ID\": \"your-user-id\"\n      }\n    }\n  }\n}\n```\n\n### Example Tool Calls\n\n#### Get Your Profile\n\n```json\n{\n  \"name\": \"threads_get_profile\",\n  \"arguments\": {}\n}\n```\n\n#### Create a Thread\n\n```json\n{\n  \"name\": \"threads_create_thread\",\n  \"arguments\": {\n    \"text\": \"Hello from the Threads MCP Server! 🚀\",\n    \"replyControl\": \"everyone\"\n  }\n}\n```\n\n#### Get Thread Insights\n\n```json\n{\n  \"name\": \"threads_get_insights\",\n  \"arguments\": {\n    \"threadId\": \"thread-id-here\",\n    \"metrics\": [\"views\", \"likes\", \"replies\", \"reposts\"]\n  }\n}\n```\n\n#### Reply to a Thread\n\n```json\n{\n  \"name\": \"threads_reply_to_thread\",\n  \"arguments\": {\n    \"threadId\": \"thread-id-to-reply-to\",\n    \"text\": \"Great post!\",\n    \"replyControl\": \"accounts_you_follow\"\n  }\n}\n```\n\n## Development\n\n### Project Structure\n\n```\nthreads-mcp/\n├── src/\n│   ├── client/           # Threads API client\n│   │   ├── __tests__/    # Client tests\n│   │   └── threads-client.ts\n│   ├── server/           # MCP server implementation\n│   │   ├── __tests__/    # Server tests\n│   │   └── server.ts\n│   ├── types/            # TypeScript types & Zod schemas\n│   │   ├── __tests__/    # Type tests\n│   │   └── threads.ts\n│   └── index.ts          # Entry point\n├── dist/                 # Compiled output\n├── coverage/             # Test coverage reports\n└── tests/                # Integration tests\n```\n\n### Available Scripts\n\n```bash\n# Development\npnpm run dev              # Run in development mode with tsx\npnpm run build            # Compile TypeScript to JavaScript\n\n# Testing\npnpm test                 # Run tests once\npnpm test:watch          # Run tests in watch mode\npnpm test:coverage       # Generate coverage report\n\n# Code Quality\npnpm run lint            # Lint code with ESLint\npnpm run format          # Format code with Prettier\n```\n\n### Running Tests\n\nThe project has comprehensive test coverage (>90%):\n\n```bash\n# Run all tests\npnpm test\n\n# Run with coverage\npnpm test:coverage\n\n# Watch mode for development\npnpm test:watch\n```\n\n### Code Quality\n\n```bash\n# Lint your code\npnpm run lint\n\n# Format code\npnpm run format\n```\n\n## API Reference\n\n### ThreadsClient\n\nThe core client for interacting with the Threads API.\n\n#### Constructor\n\n```typescript\nconst client = new ThreadsClient({\n  accessToken: string;\n  userId: string;\n  apiVersion?: string; // Optional, defaults to 'v1.0'\n});\n```\n\n#### Methods\n\n- `getProfile(fields?: string[]): Promise<ThreadsUser>`\n- `getThreads(params?: GetMediaParams): Promise<ThreadsMedia[]>`\n- `getThread(threadId: string, fields?: string[]): Promise<ThreadsMedia>`\n- `createThread(params: CreateThreadParams): Promise<CreateThreadResponse>`\n- `getThreadInsights(threadId: string, params: GetInsightsParams): Promise<ThreadsInsights[]>`\n- `getUserInsights(params: GetInsightsParams): Promise<ThreadsInsights[]>`\n- `getReplies(threadId: string, params?: GetRepliesParams): Promise<ThreadsReplies>`\n- `getConversation(threadId: string, params?: GetRepliesParams): Promise<ThreadsConversation>`\n- `replyToThread(threadId: string, text: string, replyControl?: string): Promise<CreateThreadResponse>`\n- `validateToken(): Promise<boolean>`\n\n## Error Handling\n\nThe client includes comprehensive error handling:\n\n```typescript\nimport { ThreadsAPIError } from 'threads-mcp';\n\ntry {\n  await client.createThread({ text: 'Hello!' });\n} catch (error) {\n  if (error instanceof ThreadsAPIError) {\n    console.error('API Error:', error.message);\n    console.error('Status Code:', error.statusCode);\n    console.error('Response:', error.response);\n  }\n}\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Write tests for new features (maintain >90% coverage)\n- Follow the existing code style\n- Update documentation as needed\n- Use conventional commits (enforced by Git hooks)\n\n### Git Hooks\n\nThis project uses Husky to enforce code quality:\n\n- **pre-commit**: Runs linting, formatting, and type checking\n- **pre-push**: Runs full test suite, coverage check, and build verification\n- **commit-msg**: Validates commit message format (conventional commits)\n\nSee [docs/GIT_HOOKS.md](docs/GIT_HOOKS.md) for detailed information about Git hooks.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 Pegasus Heavy Industries LLC\n\n## Support\n\n- 📚 [Threads API Documentation](https://developers.facebook.com/docs/threads)\n- 🐛 [Report Issues](https://github.com/PegasusHeavyIndustries/threads-mcp/issues)\n- 💬 [MCP Protocol Documentation](https://modelcontextprotocol.io/)\n\n## Acknowledgments\n\n- Built with [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- Powered by [Threads API](https://developers.facebook.com/docs/threads)\n- Type validation with [Zod](https://github.com/colinhacks/zod)\n- Testing with [Vitest](https://vitest.dev/)\n\n---\n\nMade with ❤️ by Pegasus Heavy Industries LLC\n"}