agent-twitter-client-mcp

agent-twitter-client-mcp

一个通过 agent-twitter-client 包与 Twitter 集成的模型上下文协议（MCP）服务，可让 AI 模型无需直接访问 API 即可与 Twitter 交互。

功能

• 身份验证选项：

  • 基于 Cookie 的身份验证（推荐）
  • 用户名/密码身份验证
  • Twitter API v2 凭据

• 推文操作：

  • 获取用户的推文
  • 按 ID 获取特定推文
  • 搜索推文
  • 发布包含文本和媒体的推文
  • 创建投票
  • 点赞、转发和引用推文

• 用户操作：

  • 获取用户资料
  • 关注用户
  • 获取粉丝和关注列表

• Grok 集成：

  • 通过 Twitter 界面与 Grok 聊天
  • 使用对话 ID 继续对话
  • 获取网页搜索结果和引文
  • 通过 Grok 访问 Twitter 实时数据
  • 注意：Grok 功能需要 agent-twitter-client v0.0.19 或更高版本

文档

• 开发者指南 - 面向开发者的综合指南
• 测试指南 - MCP 测试说明
• Agent 指南 - AI Agent 使用 Twitter MCP 的指南
• 贡献指南 - 为此项目做出贡献的指南
• 更新日志 - 此项目的变更历史
• 演示 README - 运行演示脚本的指南
• Grok 示例 - Grok AI 集成示例的文档

快速开始

安装

# Install globally
npm install -g agent-twitter-client-mcp

# Or install locally
npm install agent-twitter-client-mcp

基本用法

1. 创建一个 .env 文件并填入你的 Twitter 凭据（参见身份验证方法）
2. 运行 MCP 服务：

# If installed globally
agent-twitter-client-mcp

# If installed locally
npx agent-twitter-client-mcp

演示脚本

此软件包包含一个 demo 目录，其中提供了展示各种功能的示例脚本：

# Clone the repository to access the demo scripts
git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp/demo

# Run the interactive demo menu
./run-demo.sh

# Run a specific demo script
./run-demo.sh --script tweet-search.js

# Run Grok AI examples (requires agent-twitter-client v0.0.19)
./run-demo.sh --script simple-grok.js --use-local-agent-twitter-client
./run-demo.sh --script grok-chat.js --use-local-agent-twitter-client

更多详情请参阅演示 README。

端口配置

默认情况下，MCP 服务在端口 3000 上运行。如果需要更改端口（例如，你已有应用在端口 3000 上运行），可以通过以下几种方式进行配置：

选项 1：使用环境变量

设置 PORT 环境变量：

PORT=3001 npx agent-twitter-client-mcp

选项 2：使用 Docker Compose

如果使用 Docker Compose，可以在 .env 文件中配置主机端口和容器端口：

# .env file
MCP_HOST_PORT=3001    # The port on your host machine
MCP_CONTAINER_PORT=3000  # The port inside the container

然后运行：

docker-compose up -d

这会将主机上的端口 3001 映射到容器中的端口 3000，使你可以通过 http://localhost:3001 访问 MCP，同时让其他应用继续使用端口 3000。

使用 Claude Desktop 进行设置

1. 将以下内容添加到配置文件，以配置 Claude Desktop 使用此 MCP：

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

{
  "mcpServers": {
    "agent-twitter-client-mcp": {
      "command": "npx",
      "args": ["-y", "agent-twitter-client-mcp"],
      "env": {
        "AUTH_METHOD": "cookies",
        "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
      }
    }
  }
}

2. 重启 Claude Desktop

身份验证方法

Cookie 身份验证（推荐）

{
  "AUTH_METHOD": "cookies",
  "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
}

获取 Cookie 的步骤：

1. 在浏览器中登录 Twitter
2. 打开开发者工具（F12）
3. 转到 Application 标签页 > Cookies
4. 复制 auth_token、ct0 和 twid Cookie 的值
5. 确保每个 Cookie 都包含 Domain=.twitter.com 部分

用户名/密码身份验证

{
  "AUTH_METHOD": "credentials",
  "TWITTER_USERNAME": "your_username",
  "TWITTER_PASSWORD": "your_password",
  "TWITTER_EMAIL": "[email protected]", // Optional
  "TWITTER_2FA_SECRET": "your_2fa_secret" // Optional, required if 2FA is enabled
}

Twitter API 身份验证

{
  "AUTH_METHOD": "api",
  "TWITTER_API_KEY": "your_api_key",
  "TWITTER_API_SECRET_KEY": "your_api_secret_key",
  "TWITTER_ACCESS_TOKEN": "your_access_token",
  "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret"
}

可用工具

• get_user_tweets：获取指定用户的推文
• get_tweet_by_id：按 ID 获取指定推文
• search_tweets：搜索推文
• send_tweet：发布新推文
• send_tweet_with_poll：发布带投票的推文
• like_tweet：点赞推文
• retweet：转推
• quote_tweet：引用推文
• get_user_profile：获取用户资料
• follow_user：关注用户
• get_followers：获取用户的关注者
• get_following：获取用户关注的用户
• grok_chat：通过 Twitter 与 Grok 聊天
• health_check：检查 Twitter MCP 服务的运行状况

测试界面

MCP 提供了一个交互式命令行界面，用于测试：

npx agent-twitter-client-mcp-test
# or if installed locally
npm run test:interface

这会启动一个 REPL，你可以在其中测试各种 MCP 功能：

agent-twitter-client-mcp> help

Available commands:
  health                     Run a health check
  profile <username>         Get a user profile
  tweets <username> [count]  Get tweets from a user
  tweet <id>                 Get a specific tweet by ID
  search <query> [count]     Search for tweets
  post <text>                Post a new tweet
  like <id>                  Like a tweet
  retweet <id>               Retweet a tweet
  quote <id> <text>          Quote a tweet
  follow <username>          Follow a user
  followers <userId> [count] Get a user's followers
  following <userId> [count] Get users a user is following
  grok <message>             Chat with Grok
  help                       Show available commands
  exit                       Exit the test interface

测试命令示例

# Run a health check
agent-twitter-client-mcp> health

# Search for tweets
agent-twitter-client-mcp> search mcp 2

# Get a user's profile
agent-twitter-client-mcp> profile elonmusk

# Get tweets from a user
agent-twitter-client-mcp> tweets openai 5

# Chat with Grok
agent-twitter-client-mcp> grok Explain quantum computing in simple terms

使用示例

让 Claude 执行以下操作：

• “在 Twitter 上搜索有关 AI 的推文”
• “发布一条推文，内容为‘Hello from Claude!’”
• “获取 @OpenAI 的最新推文”
• “与 Grok 聊聊量子计算”

高级用法

处理媒体

发布带图片的推文：

I want to post a tweet with an image. The tweet should say "Beautiful sunset today!" and include this image.

发布带视频的推文：

I want to post a tweet with a video. The tweet should say "Check out this amazing video!" and include the video file.

创建投票

创建投票：

Create a Twitter poll asking "What's your favorite programming language?" with options: Python, JavaScript, Rust, and Go. The poll should run for 24 hours.

与 Grok 互动

与 Grok 进行对话：

Use Grok to explain quantum computing to me. Ask it to include some real-world applications.

继续与 Grok 对话：

Continue the Grok conversation and ask it to elaborate on quantum entanglement.

Grok 的独特能力

Twitter 上的 Grok 可以访问实时 Twitter 数据，而独立的 Grok API 无法访问这些数据。这意味着你可以询问 Grok：

• Twitter 上当前的热门话题
• 对特定主题近期推文的分析
• 有关 Twitter 用户及其内容的信息
• 平台上正在讨论的实时事件

查询示例：

• “Twitter 上现在的热门话题是什么？”
• “分析 Twitter 上关于 AI 的情绪倾向”
• “大家对最新的 Apple 发布会都在说些什么？”
• “向我展示今天正在讨论的热门 memecoin 相关信息”

Grok 身份验证要求

Grok 功能需要正确的身份验证。MCP 支持两种方式：

1. Cookie 身份验证（推荐）：

   • Cookie 必须采用 JSON 数组格式
   • 示例：TWITTER_COOKIES=["auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com", "ct0=YOUR_CT0_VALUE; Domain=.twitter.com", "twid=u%3DYOUR_USER_ID; Domain=.twitter.com"]
   • 必需的 Cookie 是 auth_token、ct0 和 twid

2. 用户名/密码身份验证：

   • 在环境中设置 TWITTER_USERNAME 和 TWITTER_PASSWORD
   • 某些情况下可能会遇到 Cloudflare 防护

Grok 速率限制

Grok 有速率限制，可能会影响使用：

• 非高级账户：每 2 小时 25 条消息
• 高级账户：限制更高

达到限制时，MCP 会在响应中返回速率限制信息。

有关 Grok 用法的更多详情，请参阅 Grok 示例文档。

故障排除

身份验证问题

Cookie 身份验证问题

如果 Cookie 身份验证遇到问题：

1. Cookie 过期：Twitter Cookie 通常会在一段时间后过期。请尝试退出并重新登录 Twitter，以刷新 Cookie。
2. Cookie 格式：请确保 Cookie 已正确格式化为包含正确域名的字符串 JSON 数组。
3. 必需的 Cookie：请确保已包含必需的 Cookie：auth_token、ct0 和 twid。

正确格式的 Cookie 示例：

"TWITTER_COOKIES": "[\"auth_token=1234567890abcdef; Domain=.twitter.com\", \"ct0=abcdef1234567890; Domain=.twitter.com\", \"twid=u%3D1234567890; Domain=.twitter.com\"]"

凭据身份验证问题

如果用户名/密码身份验证遇到问题：

1. 双重身份验证：如果账户已启用 2FA，你需要提供 TWITTER_2FA_SECRET。
2. 账户锁定：多次登录失败可能会导致账户被锁定。请检查电子邮件，查看是否有账户验证请求。
3. 验证码：Twitter 可能会要求完成验证码挑战，而客户端无法自动处理。

API 认证问题

对于 API 认证问题：

1. API 密钥权限：确保 API 密钥拥有执行所需操作的必要权限。
2. 速率限制：Twitter API 有速率限制，超出限制可能导致请求失败。
3. API 变更：Twitter 偶尔会更改其 API，这可能导致兼容性问题。

操作错误

发布推文失败

如果无法发布推文：

1. 内容限制：Twitter 可能会屏蔽违反其内容政策的推文。
2. 媒体格式问题：确保媒体格式和编码正确。
3. 速率限制：Twitter 限制了发布频率。

搜索问题

如果搜索无法正常工作：

1. 查询语法：确保搜索查询符合 Twitter 的搜索语法。
2. 搜索限制：某些搜索模式可能有限制，或需要特定权限。

Grok 问题

如果 Grok 功能无法正常工作：

1. 版本要求：

   • Grok 需要 agent-twitter-client v0.0.19 或更高版本
   • 当前软件包使用 v0.0.18，提供基本功能
   • 对于演示脚本，请使用 --use-local-agent-twitter-client 标志临时安装 v0.0.19

2. 认证问题：

   • Cookie 格式：确保 Cookie 的格式为正确的 JSON 数组
   • Cookie 有效性：Twitter Cookie 会在一段时间后过期
   • Cloudflare 保护：Cloudflare 可能会阻止用户名/密码认证
   • Premium 要求：访问 Grok 需要订阅 Twitter Premium

3. 速率限制：

   • 非 Premium 账号：每 2 小时 25 条消息
   • 错误消息："Rate Limited: You've reached the limit..."
   • 解决方案：等待速率限制重置，或升级为 Premium 账号

4. 环境文件位置：

   • 对于演示脚本，请确保凭据位于 demo/.env 中，而不是根目录的 .env 文件中
   • 使用 --debug-env 标志检查加载了哪些环境变量

有关 Grok 问题的详细故障排除信息，请参阅 Grok 示例文档。

服务问题

健康检查

使用 health_check 工具诊断服务问题：

Run a health check on the agent-twitter-client-mcp server to diagnose any issues.

健康检查将报告以下内容：

• 认证状态
• API 连接状态
• 内存使用情况

日志记录

服务会将日志同时写入控制台和文件：

• error.log：包含错误级别的消息
• combined.log：包含所有日志消息

查看这些日志以获取详细的错误信息。

开发

先决条件

• Node.js 18+
• npm

设置

1. 克隆仓库

git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp

2. 安装依赖项

npm install

3. 创建包含配置的 .env 文件：

AUTH_METHOD=cookies
TWITTER_COOKIES=["cookie1=value1", "cookie2=value2"]

4. 构建项目

npm run build

5. 启动服务

npm start

环境变量

除了认证变量外，还可以设置：

• LOG_LEVEL：设置日志级别（error、warn、info、debug）
• NODE_ENV：设置环境（development、production）

Docker

你也可以使用 Docker 运行服务：

直接使用 Docker

# Build the Docker image
docker build -t agent-twitter-client-mcp .

# Run the container with environment variables
docker run -p 3000:3000 \
  -e AUTH_METHOD=cookies \
  -e TWITTER_COOKIES='["auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com", "ct0=YOUR_CT0_VALUE; Domain=.twitter.com"]' \
  agent-twitter-client-mcp

使用 Docker Compose

1. 创建包含 Twitter 凭据的 .env 文件
2. 使用 docker-compose 运行：

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Docker 中的环境变量

可以通过以下几种方式向 Docker 容器传递环境变量：

1. 在 docker-compose.yml 文件中（已配置）
2. 通过 .env 文件（推荐用于 docker-compose）
3. 直接在 docker run 命令中（如上所示）

持久化日志

docker-compose 配置包含用于日志的卷挂载：

volumes:
  - ./logs:/app/logs

这会将日志存储在项目文件夹中的 logs 目录下。

安全注意事项

• 凭据存储：安全地存储凭据，最好使用环境变量或安全保管库。
• 速率限制：实施速率限制，以防止滥用 Twitter API。
• 内容验证：发布前验证所有内容，以防止恶意使用。

许可证

MIT