X/Twitter MCP Server

X/Twitter MCP 服务

一个模型上下文协议（MCP）服务，通过使用 Playwright 的浏览器自动化功能，提供非官方的 X/Twitter API 访问能力。此服务支持 AI Agent 和应用以编程方式与 X/Twitter 交互，用于内容创作、抓取和社交媒体自动化。

🚀 功能

内容创作与互动

• 推文与串文发布：发布单条推文或多条推文组成的串文，并支持媒体
• 帖子互动：点赞、取消点赞、转发、取消转发、收藏、引用推文和回复帖子
• 评论管理：点赞、取消点赞、回复和编辑评论
• 媒体支持：向推文上传并附加图片、视频和 GIF

内容抓取与分析

• 时间线抓取：从“For You”和“Following”时间线提取帖子
• 个人资料抓取：获取全面的用户个人资料数据和近期帖子
• 搜索功能：通过筛选条件进行高级搜索，包括热门内容、特定用户和日期范围
• 评论抓取：从特定帖子提取评论和回复
• 热门话题：获取当前热门话题和标签

MCP 集成

• 双传输支持：支持 stdio 和 HTTP/SSE 传输
• 基于工具的接口：提供 20 多种工具，供 AI Agent 与 X/Twitter 交互
• 结构化响应：提供包含全面元数据的 JSON 格式响应
• 错误处理：提供可靠的错误处理和清晰的错误消息

📋 前置条件

• Node.js 18+
• 有效的 X/Twitter 账号凭据
• Docker（可选，用于容器化部署）

快速开始

1. 将此配置添加到 Claude Desktop 配置文件中：

Windows：%APPDATA%\Claude\claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": ["-y", "@barresider/x-mcp"],
      "env": {
        "TWITTER_USERNAME": "your_twitter_username",
        "TWITTER_PASSWORD": "your_twitter_password"
      }
    }
  }
}

使用代理（可选）：

{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": ["-y", "@barresider/x-mcp"],
      "env": {
        "TWITTER_USERNAME": "your_twitter_username",
        "TWITTER_PASSWORD": "your_twitter_password",
        "PROXY_URL": "http://proxy-server:port"
      }
    }
  }
}

2. 重启 Claude Desktop

完成！现在，Claude 可以通过 25 多种强大工具与 X/Twitter 交互，包括：

• tweet：发布带有可选媒体的新推文
• thread：发布多条推文组成的串文
• search_twitter：使用高级筛选条件搜索推文
• scrape_profile：获取全面的用户个人资料数据
• scrape_timeline：从时间线提取帖子
• like_post、retweet_post、bookmark_post：与帖子互动
• 以及更多用于全面自动化 X/Twitter 的工具

使用示例

可以尝试向 Claude 提问：

• “可以发布一条内容为‘Hello from Claude!’的推文吗？”
• “可以搜索关于 Claude AI 的推文吗？”
• “可以抓取 Elon Musk 的个人资料，并向我展示他最近的 5 条推文吗？”
• “可以发布一条关于 AI 优势的串文吗？”

🛠️ 安装

本地开发安装

1. 克隆仓库：

git clone <repository-url>
cd x-mcp

2. 安装依赖：

npm install

3. 构建项目：

npm run build

Docker 安装

1. 构建 Docker 镜像：

docker build -t x-mcp .

2. 或使用 Docker Compose：

docker-compose --profile mcp up --build

⚙️ 配置

环境变量

在项目根目录创建 .env 文件：

# Required: X/Twitter credentials
TWITTER_USERNAME=your_username
TWITTER_PASSWORD=your_password

# Optional: Proxy configuration
PROXY_URL=http://proxy-server:port          # Full proxy URL (supports http/https)
# or with authentication
PROXY_URL=http://username:password@proxy-server:port
# or separately
PROXY_URL=http://proxy-server:port
PROXY_USERNAME=proxy_username               # Optional: separate username
PROXY_PASSWORD=proxy_password               # Optional: separate password

# Optional: MCP server configuration
MCP_TRANSPORT=stdio           # Options: stdio, sse, http
MCP_PORT=3000                # Port for HTTP/SSE transport

# Optional: Directory for authentication state (default: playwright/.auth)
AUTH_DIR=playwright/.auth

身份验证设置

1. （可选）创建身份验证目录，或设置 AUTH_DIR 环境变量：

export AUTH_DIR=/path/to/auth/dir
mkdir -p "${AUTH_DIR:-playwright/.auth}"

2. 登录 X/Twitter（保存会话以供重复使用）：

npm run cli login
# or
node dist/cli.js login

🔧 可用的 MCP 工具

此服务提供 25 多种工具，可全面地与 X/Twitter 交互：

身份验证与设置

• login - 使用 X/Twitter 进行身份验证

内容创作

• tweet - 发布带有可选媒体的单条推文
• thread - 发布多条推文组成的串文
• reply_to_post - 回复特定帖子
• quote_tweet - 引用推文并附加文本

帖子互动

• like_post / unlike_post - 点赞/取消点赞帖子
• retweet_post / unretweet_post - 转发/取消转发帖子
• bookmark_post / unbookmark_post - 管理收藏

评论互动

• like_comment_by_id / unlike_comment_by_id - 点赞/取消点赞评论
• reply_to_comment_by_id - 回复评论
• replace_comment_by_id - 编辑评论（如果支持）

内容抓取

• scrape_posts - 抓取当前页面中的帖子
• scrape_profile - 获取用户资料和近期帖子
• scrape_comments - 提取帖子中的评论
• scrape_timeline - 抓取 For You/Following 时间线
• scrape_trending - 获取热门话题
• search_twitter - 通用搜索功能
• search_viral - 搜索达到最低互动量要求的热门内容

📊 数据结构

TwitterPost

interface TwitterPost {
  postId: string;
  author: TwitterUser;
  content: string;
  timestamp: Date;
  media: TwitterMedia[];
  metrics: PostMetrics;
  engagementRate: number;
  isRetweet?: boolean;
  retweetedFrom?: TwitterUser;
  quotedPost?: TwitterPost;
  url: string;
}

TwitterProfile

interface TwitterProfile extends TwitterUser {
  bannerUrl?: string;
  bio?: string;
  location?: string;
  website?: string;
  joinedDate?: Date;
  followingCount: number;
  followersCount: number;
  postsCount: number;
  isFollowing?: boolean;
  isFollowedBy?: boolean;
  latestPosts?: TwitterPost[];
}

PostMetrics

interface PostMetrics {
  likesCount: number;
  retweetsCount: number;
  quotesCount: number;
  repliesCount: number;
  impressionsCount: number;
  bookmarksCount: number;
}

🔒 安全与最佳实践

速率限制

• 在请求之间加入延迟，避免触发速率限制
• 为抓取操作设置合理的限制
• 监控速率限制响应

身份验证

• 将凭据安全地存储在环境变量中
• 会话数据存储在 AUTH_DIR 环境变量指定的目录中（默认值为 playwright/.auth/）
• 可能需要定期重新进行身份验证

错误处理

• 所有操作均包含完善的错误处理
• 提供清晰的错误消息以便排查问题
• 缺少元素时可优雅降级

代理配置

• 支持为所有浏览器连接配置 HTTP/HTTPS 代理
• 通过 PROXY_URL 环境变量进行配置
• 支持使用用户名/密码进行身份验证
• 适用于：
  • 轮换 IP 地址以避免速率限制
  • 从受限网络访问 X/Twitter
  • 增加一层匿名保护
• 示例格式：
  • 基本格式：http://proxy-server:port
  • 带身份验证：http://username:password@proxy-server:port
  • 单独配置身份验证：使用 PROXY_USERNAME 和 PROXY_PASSWORD

🐳 Docker 部署

使用 Docker Compose

# Start the MCP server
docker-compose --profile mcp up

# With environment variables
TWITTER_USERNAME=your_username TWITTER_PASSWORD=your_password docker-compose --profile mcp up

自定义 Docker 运行命令

docker run -d \
  --name x-mcp \
  -e TWITTER_USERNAME=your_username \
  -e TWITTER_PASSWORD=your_password \
  -e PROXY_URL=http://proxy-server:port \
  -e MCP_TRANSPORT=sse \
  -e MCP_PORT=3000 \
  -p 3000:3000 \
  x-mcp

🛠️ 开发

项目结构

src/
├── mcp.ts                    # Main MCP server implementation
├── cli.ts                    # Command line interface
├── types.ts                  # TypeScript type definitions
├── utils.ts                  # Utility functions
├── behaviors/                # User interaction behaviors
│   ├── login.ts             # Authentication logic
│   ├── interact-with-post.ts # Post interaction functions
│   ├── interact-with-comment.ts # Comment interaction functions
│   └── upload-media.ts      # Media upload functionality
└── scrapers/                # Data scraping modules
    ├── index.ts             # Scraper exports
    ├── post-scraper.ts      # Post scraping logic
    ├── profile-scraper.ts   # Profile scraping logic
    ├── comment-scraper.ts   # Comment scraping logic
    ├── search-scraper.ts    # Search functionality
    ├── timeline-scraper.ts  # Timeline scraping
    └── utils.ts             # Scraping utilities

构建与测试

# Build TypeScript
npm run build

# Run MCP server
npm run mcp

# Run CLI commands
npm run cli <command>

🤝 贡献

1. Fork 此代码库
2. 创建功能分支
3. 进行修改
4. 充分测试
5. 提交拉取请求

指南

• 遵循 TypeScript 最佳实践
• 添加完善的错误处理
• 为新功能更新类型定义
• 使用真实的 X/Twitter 交互进行测试
• 记录新功能

⚠️ 免责声明

• 这是一个使用浏览器自动化技术的非官方工具
• 适用 X/Twitter 的服务条款
• 请负责任地使用，并遵守速率限制
• UI 更改可能需要更新选择器
• 与 X/Twitter 无关联

📄 许可证

[此处填写许可证信息]

🐛 故障排除

常见问题

身份验证失败

• 验证 .env 文件中的凭据
• 使用 npm run cli login 再次尝试登录
• 检查是否需要 2FA

未找到元素错误

• X/Twitter 可能已更新其 UI
• 清除浏览器缓存并重新进行身份验证
• 检查是否需要更新元素选择器

速率限制

• 降低请求频率
• 在操作之间加入延迟
• 使用较小的批次

容器问题

• 确保环境变量配置正确
• 检查端口是否可用
• 验证 Docker 网络配置

如需更多帮助，请在项目代码库中提交 issue。