Agent Twitter Client MCP

代理twitter客户端mcp

一个模型上下文协议（MCP）服务器，使用 agent-twitter-client 包，允许人工智能模型与Twitter交互，而无需直接访问API。

特性

• 身份验证选项:

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

• 推特操作:

- 从用户那里获取推文 - 按ID获取特定推文 - 搜索推文 - 发送带有文本和媒体的推文 - 创建投票 - 点赞、转发和引用推文

• 用户操作:

- 获取用户资料 - 关注用户 - 获取关注者和关注列表

• Grok集成:

- 通过推特界面与Grok聊天 - 使用对话ID继续对话 - 获取网络搜索结果和引用 - 通过Grok访问Twitter的实时数据 - 备注：Grok功能需要 代理推特客户端v0.0.19 或更高

文档

• 开发者指南 -开发人员综合指南
• 测试指导 -MCP测试说明
• 代理商指南 -关于如何使用Twitter MCP的AI代理指南
• 贡献指南 -为本项目做出贡献的指南
• 更新日志 -此项目的变更历史
• 演示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，允许您在以下位置访问MCPhttp://localhost:3001而您的其他应用程序继续使用端口3000。

使用Claude Desktop进行设置

1. 通过在配置文件中添加以下内容来配置Claude Desktop以使用此MCP：

视窗: %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\"]"
      }
    }
  }
}

1. 重新启动克劳德桌面

身份验证方法

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. 在浏览器中登录推特
2. 打开开发人员工具（F12）
3. 转到应用程序选项卡>Cookie
4. 复制以下值 auth_token, ct0，以及 twid 饼干
5. 确保包括 Domain=.twitter.com 每个饼干的一部分

用户名/密码验证

{
  "AUTH_METHOD": "credentials",
  "TWITTER_USERNAME": "your_username",
  "TWITTER_PASSWORD": "your_password",
  "TWITTER_EMAIL": "your_email@example.com", // 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：通过推特与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          Get a user profile
  tweets  [count]  Get tweets from a user
  tweet                  Get a specific tweet by ID
  search  [count]     Search for tweets
  post                 Post a new tweet
  like                   Like a tweet
  retweet                Retweet a tweet
  quote            Quote a tweet
  follow           Follow a user
  followers  [count] Get a user's followers
  following  [count] Get users a user is following
  grok              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

示例用法

请克劳德：

• “在推特上搜索有关人工智能的推文”
• “发一条推特说‘克劳德你好！’”
• “从@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的独特能力

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

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

示例查询：

• “现在推特上的热门话题是什么？”
• “分析推特上围绕人工智能的情绪”
• “人们对苹果最近的活动有什么看法？”
• “向我展示今天讨论的流行模因币的信息”

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"] - 基本饼干是 auth_token, ct0，以及 twid

1. 用户名/密码验证:

- 集 TWITTER_USERNAME 和 TWITTER_PASSWORD 在您的环境中 - 在某些情况下可能会遇到Cloudflare保护

Grok费率限制

Grok有可能影响使用的费率限制：

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

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

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

故障排除

身份验证问题

Cookie身份验证问题

如果您遇到cookie身份验证问题：

1. Cookie过期：推特Cookie通常在一段时间后过期。尝试通过注销并重新登录推特来刷新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. 验证码挑战：推特可能会出现验证码挑战，客户无法自动处理。

API身份验证问题

对于API身份验证问题：

1. API密钥权限：确保您的API密钥对您尝试执行的操作具有必要的权限。
2. 速率限制：Twitter API有速率限制，如果超过速率限制，可能会导致故障。
3. API变更：Twitter偶尔会更改其API，这可能会导致兼容性问题。

操作错误

推特发布失败

如果你不能发布推文：

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

搜索问题

如果搜索不起作用：

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

Grok问题

如果Grok功能不起作用：

1. 版本要求:

- Grok需要 代理推特客户端v0.0.19 或更高 - 当前软件包使用v0.0.18实现基本功能 - 对于演示脚本，请使用 --use-local-agent-twitter-client 临时安装v0.0.19的标志

1. 身份验证问题:

- Cookie格式：确保Cookie采用正确的JSON数组格式 - Cookie有效期：推特Cookie在一段时间后过期 - Cloudflare保护：用户名/密码身份验证可能被Cloudflare阻止 - 高级要求：Grok访问需要Twitter高级订阅

1. 速率限制:

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

1. 环境文件位置:

- 对于演示脚本，请确保您的凭据在 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

1. 安装依赖项

npm install

1. 创建一个 .env 配置文件：

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

1. 构建项目

npm run build

1. 启动服务器

npm start

环境变量

除了身份验证变量外，您还可以设置：

• LOG_LEVEL：设置日志记录级别（错误、警告、信息、调试）
• NODE_ENV：设定环境（开发、生产）

码头工人

您还可以使用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. 创建一个 .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。
• 内容效度：在发布之前验证所有内容，以防止恶意使用。

许可证

麻省理工学院