Agent Twitter Client Mcp

TypeScript

MIT License

ryanmac

最近更新：2个月前

一个模型上下文协议（MCP）服务器，通过使用 @elizaOS 的 `agent-twitter-client` 包与 X 集成，使 AI 模型能够在没有直接 API 访问的情况下与 Twitter 交互。

概述

agent-twitter-client-mcp

一个使用 agent-twitter-client 包与 Twitter 集成的 Model Context Protocol (MCP) 服务器，允许 AI 模型在不直接访问 API 的情况下与 Twitter 交互。

特性

认证选项：
- 基于 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 集成示例的文档

快速开始

安装

bash 复制代码

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

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

基本用法

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

bash 复制代码

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

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

演示脚本

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

bash 复制代码

# 克隆仓库以访问演示脚本
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 环境变量：

bash 复制代码

PORT=3001 npx agent-twitter-client-mcp

选项 2：使用 Docker Compose

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

复制代码

# .env 文件
MCP_HOST_PORT=3001    # 主机上的端口
MCP_CONTAINER_PORT=3000  # 容器内的端口

然后运行：

bash 复制代码

docker-compose up -d

这将把主机上的 3001 端口映射到容器内的 3000 端口，允许您在 http://localhost:3001 访问 MCP，而您的其他应用程序继续使用 3000 端口。

与 Claude Desktop 配置

在配置文件中配置 Claude Desktop 以使用此 MCP：

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

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\"]"
      }
    }
  }
}

重启 Claude Desktop

认证方法

json 复制代码

{
  "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 的步骤：

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

用户名/密码认证

json 复制代码

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

Twitter API 认证

json 复制代码

{
  "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 包括一个用于测试的交互式命令行界面：

bash 复制代码

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 聊天讨论量子计算"

高级用法

处理媒体

要发布带有图片的推文：

复制代码

我想发布一条带有图片的推文。推文内容应该是 "Beautiful sunset today!" 并包含这张图片。

要发布带有视频的推文：

复制代码

我想发布一条带有视频的推文。推文内容应该是 "Check out this amazing video!" 并包含这个视频文件。

创建投票

要创建投票：

复制代码

创建一个 Twitter 投票，问题为 "What's your favorite programming language?" 选项包括 Python, JavaScript, Rust 和 Go。投票应持续 24 小时。

与 Grok 互动

要与 Grok 对话：

复制代码

让 Grok 向我解释量子计算。请它包括一些实际应用。

要继续与 Grok 的对话：

复制代码

继续与 Grok 的对话并询问它关于量子纠缠的详细信息。

Grok 的独特功能

Grok 在 Twitter 上可以访问实时 Twitter 数据，即使是独立的 Grok API 也无法访问这些数据。这意味着您可以向 Grok 询问：

当前 Twitter 上的热门话题
对特定主题的最近推文的情绪分析
关于 Twitter 用户及其内容的信息
平台上讨论的实时事件

示例查询：

"当前 Twitter 上的热门话题是什么？"
"分析 Twitter 上关于 AI 的情绪"
"人们在谈论最新的苹果发布会吗？"
"显示今天讨论的热门 meme 币的信息"

Grok 认证要求

Grok 功能需要正确的认证。MCP 支持两种方法：

基于 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
用户名/密码认证：
- 在环境中设置 TWITTER_USERNAME 和 TWITTER_PASSWORD
- 在某些情况下可能会遇到 Cloudflare 保护

Grok 速率限制

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

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

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

有关使用 Grok 的更多详细信息，请参阅 Grok 示例文档。

故障排除

认证问题

如果您遇到基于 Cookie 的认证问题：

Cookie 过期：Twitter Cookie 通常会在一段时间后过期。尝试注销并重新登录 Twitter 以刷新 Cookie。
Cookie 格式：确保您的 Cookie 正确格式化为具有正确域的 JSON 字符串数组。
必需的 Cookie：确保您包含了必需的 Cookie：auth_token、ct0 和 twid

正确格式化的 Cookie 示例：

json 复制代码

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

凭证认证问题

如果您遇到用户名/密码认证问题：

两步验证：如果您的帐户启用了两步验证，则需要提供 TWITTER_2FA_SECRET。
帐户锁定：多次失败的登录尝试可能会锁定您的帐户。检查您的电子邮件以获取帐户验证请求。
验证码挑战：Twitter 可能会呈现客户端无法自动处理的验证码挑战。

API 认证问题

对于 API 认证问题：

API 密钥权限：确保您的 API 密钥具有执行所需操作所需的权限。
速率限制：Twitter API 有速率限制，超过限制可能导致失败。
API 更改：Twitter 偶尔会更改其 API，这可能会导致兼容性问题。

操作错误

推文发布失败

如果您无法发布推文：

内容限制：Twitter 可能会阻止违反其内容政策的推文。
媒体格式问题：确保媒体格式正确且已编码。
速率限制：Twitter 限制了您发布推文的频率。

搜索问题

如果搜索不起作用：

查询语法：确保您的搜索查询遵循 Twitter 的搜索语法。
搜索限制：某些搜索模式可能有限制或需要特定权限。

Grok 问题

如果 Grok 功能不起作用：

版本要求：
- Grok 需要 agent-twitter-client v0.0.19 或更高版本
- 当前包使用 v0.0.18 用于基本功能
- 对于演示脚本，使用 --use-local-agent-twitter-client 标志临时安装 v0.0.19
认证问题：
- Cookie 格式：确保 Cookie 采用正确的 JSON 数组格式
- Cookie 有效性：Twitter Cookie 会在一段时间后过期
- Cloudflare 保护：用户名/密码认证可能会被 Cloudflare 阻止
- 高级要求：Grok 访问需要 Twitter 高级订阅
速率限制：
- 非高级账户：每 2 小时 25 条消息
- 错误信息："Rate Limited: You've reached the limit..."
- 解决方案：等待速率限制重置或升级到高级账户
环境文件位置：
- 对于演示脚本，确保您的凭据位于 demo/.env 中，而不是根目录的 .env 文件
- 使用 --debug-env 标志检查加载了哪些环境变量

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

服务器问题

健康检查

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

复制代码

对 agent-twitter-client-mcp 服务器运行健康检查以诊断任何问题。

健康检查将报告：

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

日志

服务器同时记录到控制台和文件：

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

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

开发

前提条件

Node.js 18+
npm

设置

克隆仓库

bash 复制代码

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

安装依赖项

bash 复制代码

npm install

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

复制代码

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

构建项目

bash 复制代码

npm run build

启动服务器

bash 复制代码

npm start

环境变量

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

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

Docker

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

直接使用 Docker

bash 复制代码

# 构建 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

创建一个包含您的 Twitter 凭证的 .env 文件
使用 docker-compose 运行：

bash 复制代码

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

Docker 中的环境变量

您可以以多种方式将环境变量传递给 Docker 容器：

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

持久化日志

docker-compose 配置包括日志卷挂载：

yaml 复制代码

volumes:
  - ./logs:/app/logs

这将在项目的 logs 目录中存储日志。

安全考虑

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

许可

MIT