agent-twitter-client-mcp

一个模型上下文协议 (MCP) 服务器，它使用 agent-twitter-client 包与 Twitter 集成，允许 AI 模型与 Twitter 交互，而无需直接访问 API。

特性

• 身份验证选项:

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

• 推文操作:

  • 从用户获取推文
  • 通过 ID 获取特定推文
  • 搜索推文
  • 发送带有文本和媒体的推文
  • 创建投票
  • 喜欢、转发和引用推文

• 用户操作:

  • 获取用户个人资料
  • 关注用户
  • 获取关注者和关注列表

• Grok 集成:

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

文档

• 开发者指南 - 针对开发者的综合指南
• 测试指南 - 测试 MCP 的说明
• 代理指南 - 关于 AI 代理如何使用 Twitter MCP 的指南
• 贡献指南 - 为本项目贡献的指南
• 变更日志 - 本项目变更历史
• 演示 README - 运行演示脚本的指南
• Grok 示例 - Grok AI 集成示例的文档

快速开始

安装

# 全局安装
npm install -g agent-twitter-client-mcp

# 或者本地安装
npm install agent-twitter-client-mcp

基本用法

1. 创建一个包含您的 Twitter 凭据的 .env 文件（参见 身份验证方法）
2. 运行 MCP 服务器：

# 如果全局安装
agent-twitter-client-mcp

# 如果本地安装
npx agent-twitter-client-mcp

演示脚本

该软件包包含一个 demo 目录，其中包含演示各种功能的示例脚本：

# 克隆存储库以访问演示脚本
git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp/demo

# 运行交互式演示菜单
./run-demo.sh

# 运行特定的演示脚本
./run-demo.sh --script tweet-search.js

# 运行 Grok AI 示例 (需要 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 文件
MCP_HOST_PORT=3001    # 主机上的端口
MCP_CONTAINER_PORT=3000  # 容器内的端口

然后运行：

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. 转到“应用程序”选项卡 > “Cookie”
4. 复制 auth_token、ct0 和 twid Cookie 的值
5. 确保为每个 Cookie 包含 Domain=.twitter.com 部分

用户名/密码身份验证

{
  "AUTH_METHOD": "credentials",
  "TWITTER_USERNAME": "your_username",
  "TWITTER_PASSWORD": "your_password",
  "TWITTER_EMAIL": "your_email@example.com", // 可选
  "TWITTER_2FA_SECRET": "your_2fa_secret" // 可选，如果启用了 2FA，则为必需
}

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
# 或者如果本地安装
npm run test:interface

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

agent-twitter-client-mcp> help

可用命令:
  health                     运行运行状况检查
  profile <username>         获取用户个人资料
  tweets <username> [count]  获取用户的推文
  tweet <id>                 通过 ID 获取特定推文
  search <query> [count]     搜索推文
  post <text>                发布新推文
  like <id>                  喜欢推文
  retweet <id>               转发推文
  quote <id> <text>          引用推文
  follow <username>          关注用户
  followers <userId> [count] 获取用户的关注者
  following <userId> [count] 获取用户正在关注的用户
  grok <message>             与 Grok 聊天
  help                       显示可用命令
  exit                       退出测试界面

示例测试命令

# 运行运行状况检查
agent-twitter-client-mcp> health

# 搜索推文
agent-twitter-client-mcp> search mcp 2

# 获取用户的个人资料
agent-twitter-client-mcp> profile elonmusk

# 获取用户的推文
agent-twitter-client-mcp> tweets openai 5

# 与 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 可以访问即使是独立的 Grok API 也没有的实时 Twitter 数据。这意味着您可以向 Grok 询问：

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

示例查询：

• "What are the trending topics on Twitter right now?"
• "Analyze the sentiment around AI on Twitter"
• "What are people saying about the latest Apple event?"
• "Show me information about popular memecoins being discussed today"

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. Captcha 挑战：Twitter 可能会显示客户端无法自动处理的 captcha 挑战。

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 阻止
   • 高级要求：Grok 访问需要 Twitter Premium 订阅

3. 速率限制：

   • 非高级帐户：每 2 小时 25 条消息
   • 错误消息：“速率限制：您已达到限制...”
   • 解决方案：等到速率限制重置或升级到高级帐户

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：设置日志记录级别（错误、警告、信息、调试）
• NODE_ENV：设置环境（开发、生产）

Docker

您还可以使用 Docker 运行服务器：

直接使用 Docker

# 构建 Docker 镜像
docker build -t agent-twitter-client-mcp .

# 使用环境变量运行容器
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 运行：

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
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