使用说明

线程MCP服务器

功能强大的模型上下文协议（MCP）服务器，用于与Threads.com API集成。此服务器提供了用于以编程方式创建、读取和管理Threads内容的全面工具。

🌐 访问网站 为了更好的阅读体验！

特性

🚀 完整的线程API集成 -全面支持Threads.com API v1.0
🔧 MCP协议 -标准模型上下文协议实现
📊 分析与洞察 -访问参与度指标和分析
💬 会话管理 -创建线程、回复和管理对话
🎯 类型安全 -通过Zod模式验证完全支持TypeScript
⚡ 速率限制 -防止违反API速率限制的令牌桶算法
💾 缓存层 -带TTL和LRU逐出的内存缓存
🔔 Webhook支持 -基于事件的webhooks，具有自动重试和签名验证功能
✅ 测试良好 -Vitest的测试覆盖率>90%
🔄 现代堆栈 -使用最新的npm包和最佳实践构建

可用工具

服务器提供以下MCP工具：

配置文件和内容管理

threads_get_profile -获取经过身份验证的用户的个人资料信息
threads_get_threads -使用分页检索用户的帖子
threads_get_thread -按ID获取特定线程
threads_create_thread -使用文本、图像或视频创建新线程
threads_reply_to_thread -回复现有线程

参与度和分析

threads_get_insights -获取线程或用户帐户的分析
threads_get_replies -检索对特定线程的回复
threads_get_conversation -获取完整的对话线索

先决条件

在开始之前，您需要：

Node.js 18+ - 点击此处下载
pnpm -安装时使用 npm install -g pnpm
元开发人员帐户 - 在这里注册
线程帐户 -您的个人Threads帐户
OAuth 2.0凭据 -请参阅 OAuth设置指南

获取线程API凭据

⚠️ 重要：Threads使用OAuth 2.0身份验证。不能使用简单的API键。

快速设置（自动OAuth）

创建元应用程序
- 访问面向开发人员的Meta
- 创建新应用程序并添加Threads API产品
- 添加OAuth重定向类型： http://localhost:48810/callback
- 得到你的 应用程序ID 和 应用密钥
配置Claude桌面
- 仅使用您的应用程序ID和密码添加到您的Claude Desktop配置中
- 服务器将在首次运行时自动处理OAuth
- 浏览器将为您打开以授权该应用程序
- 令牌被存储并自动刷新！

就是这样！无需手动OAuth流程。 🎉

📖 详细说明，请参阅 OAuth设置指南

安装

来自npm（发布时）

pnpm install -g threads-mcp

来源

# Clone the repository
git clone https://github.com/PegasusHeavyIndustries/threads-mcp.git
cd threads-mcp

# Install dependencies
pnpm install

# Build the project
pnpm run build

配置

自动OAuth（推荐）

最简单的方法是让服务器自动处理OAuth：

适用于克劳德桌面，编辑您的配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@pegasusheavy/threads-mcp"],
      "env": {
        "THREADS_APP_ID": "your-app-id",
        "THREADS_APP_SECRET": "your-app-secret"
      }
    }
  }
}

启动Claude Desktop时：

浏览器将自动打开
登录并授权应用程序
完成！令牌被存储并自动刷新

手动令牌（传统）

如果您更喜欢使用预生成的令牌：

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@pegasusheavy/threads-mcp"],
      "env": {
        "THREADS_ACCESS_TOKEN": "your-long-lived-token",
        "THREADS_USER_ID": "your-user-id"
      }
    }
  }
}

看 OAuth设置指南获取手动OAuth流程说明。

用法

运行服务器

# If installed globally
threads-mcp

# If running from source
pnpm run dev

与MCP客户端一起使用

配置您的MCP客户端（如Claude Desktop）以使用此服务器：

{
  "mcpServers": {
    "threads": {
      "command": "threads-mcp",
      "env": {
        "THREADS_ACCESS_TOKEN": "your-access-token",
        "THREADS_USER_ID": "your-user-id"
      }
    }
  }
}

工具调用示例

获取您的个人资料

{
  "name": "threads_get_profile",
  "arguments": {}
}

创建一个线程

{
  "name": "threads_create_thread",
  "arguments": {
    "text": "Hello from the Threads MCP Server! 🚀",
    "replyControl": "everyone"
  }
}

获取线索洞察

{
  "name": "threads_get_insights",
  "arguments": {
    "threadId": "thread-id-here",
    "metrics": ["views", "likes", "replies", "reposts"]
  }
}

回复一个帖子

{
  "name": "threads_reply_to_thread",
  "arguments": {
    "threadId": "thread-id-to-reply-to",
    "text": "Great post!",
    "replyControl": "accounts_you_follow"
  }
}

发展

项目结构

threads-mcp/
├── src/
│   ├── client/           # Threads API client
│   │   ├── __tests__/    # Client tests
│   │   └── threads-client.ts
│   ├── server/           # MCP server implementation
│   │   ├── __tests__/    # Server tests
│   │   └── server.ts
│   ├── types/            # TypeScript types & Zod schemas
│   │   ├── __tests__/    # Type tests
│   │   └── threads.ts
│   └── index.ts          # Entry point
├── dist/                 # Compiled output
├── coverage/             # Test coverage reports
└── tests/                # Integration tests

可用脚本

# Development
pnpm run dev              # Run in development mode with tsx
pnpm run build            # Compile TypeScript to JavaScript

# Testing
pnpm test                 # Run tests once
pnpm test:watch          # Run tests in watch mode
pnpm test:coverage       # Generate coverage report

# Code Quality
pnpm run lint            # Lint code with ESLint
pnpm run format          # Format code with Prettier

运行测试

该项目具有全面的测试覆盖率（>90%）：

# Run all tests
pnpm test

# Run with coverage
pnpm test:coverage

# Watch mode for development
pnpm test:watch

代码质量

# Lint your code
pnpm run lint

# Format code
pnpm run format

api参考

Threads客户端

用于与线程API交互的核心客户端。

构造函数

const client = new ThreadsClient({
  accessToken: string;
  userId: string;
  apiVersion?: string; // Optional, defaults to 'v1.0'
});

方法

getProfile(fields?: string[]): Promise<ThreadsUser>
getThreads(params?: GetMediaParams): Promise<ThreadsMedia[]>
getThread(threadId: string, fields?: string[]): Promise<ThreadsMedia>
createThread(params: CreateThreadParams): Promise<CreateThreadResponse>
getThreadInsights(threadId: string, params: GetInsightsParams): Promise<ThreadsInsights[]>
getUserInsights(params: GetInsightsParams): Promise<ThreadsInsights[]>
getReplies(threadId: string, params?: GetRepliesParams): Promise<ThreadsReplies>
getConversation(threadId: string, params?: GetRepliesParams): Promise<ThreadsConversation>
replyToThread(threadId: string, text: string, replyControl?: string): Promise<CreateThreadResponse>
validateToken(): Promise<boolean>

错误处理

客户端包括全面的错误处理：

import { ThreadsAPIError } from 'threads-mcp';

try {
  await client.createThread({ text: 'Hello!' });
} catch (error) {
  if (error instanceof ThreadsAPIError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  }
}

贡献

欢迎投稿！请随时提交拉取请求。

克隆该仓库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'feat: add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

开发指南

为新功能编写测试（保持>90%的覆盖率）
遵循现有代码样式
根据需要更新文档
使用常规提交（由Git钩子强制执行）

Git挂钩

该项目使用Husky来提高代码质量：

预承诺：运行linting、格式化和类型检查
预推：运行完整的测试套件、覆盖率检查和构建验证
提交消息：验证提交消息格式（常规提交）

看 docs/GIT_HOOKS.md 有关Git钩子的详细信息。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

支持

致谢

内置于 MCP-SDK
由...驱动线程API
类型验证萨德
测试与 Vitest

由以下材料制成❤️ Pegasus重工有限责任公司