{"id":36967951,"url":"https://github.com/pegasusheavy/threads-mcp","last_synced_at":"2026-01-13T20:59:51.307Z","repository":{"id":328854908,"uuid":"1117046067","full_name":"pegasusheavy/threads-mcp","owner":"pegasusheavy","description":"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. 90%+ test coverage.","archived":false,"fork":false,"pushed_at":"2026-01-03T18:45:47.000Z","size":1186,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-06T23:31:40.505Z","etag":null,"topics":["ai","api-client","caching","chatgpt","claude","mcp","model-context-protocol","rate-limiting","sdk","threads","threads-api","threads-mcp","threads-sdk","typescript","webhooks"],"latest_commit_sha":null,"homepage":"https://pegasusheavy.github.io/threads-mcp/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pegasusheavy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-15T18:48:27.000Z","updated_at":"2026-01-03T18:45:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pegasusheavy/threads-mcp","commit_stats":null,"previous_names":["pegasusheavy/threads-mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/pegasusheavy/threads-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pegasusheavy%2Fthreads-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pegasusheavy%2Fthreads-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pegasusheavy%2Fthreads-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pegasusheavy%2Fthreads-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pegasusheavy","download_url":"https://codeload.github.com/pegasusheavy/threads-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pegasusheavy%2Fthreads-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","api-client","caching","chatgpt","claude","mcp","model-context-protocol","rate-limiting","sdk","threads","threads-api","threads-mcp","threads-sdk","typescript","webhooks"],"created_at":"2026-01-13T20:59:50.440Z","updated_at":"2026-01-13T20:59:51.301Z","avatar_url":"https://github.com/pegasusheavy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"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 \u0026 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** - \u003e90% 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 \u0026 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 \u0026 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 \u0026 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 (\u003e90%):\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\u003cThreadsUser\u003e`\n- `getThreads(params?: GetMediaParams): Promise\u003cThreadsMedia[]\u003e`\n- `getThread(threadId: string, fields?: string[]): Promise\u003cThreadsMedia\u003e`\n- `createThread(params: CreateThreadParams): Promise\u003cCreateThreadResponse\u003e`\n- `getThreadInsights(threadId: string, params: GetInsightsParams): Promise\u003cThreadsInsights[]\u003e`\n- `getUserInsights(params: GetInsightsParams): Promise\u003cThreadsInsights[]\u003e`\n- `getReplies(threadId: string, params?: GetRepliesParams): Promise\u003cThreadsReplies\u003e`\n- `getConversation(threadId: string, params?: GetRepliesParams): Promise\u003cThreadsConversation\u003e`\n- `replyToThread(threadId: string, text: string, replyControl?: string): Promise\u003cCreateThreadResponse\u003e`\n- `validateToken(): Promise\u003cboolean\u003e`\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 \u003e90% 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpegasusheavy%2Fthreads-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpegasusheavy%2Fthreads-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpegasusheavy%2Fthreads-mcp/lists"}