使用说明

代理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

基本用法

创建一个 .env 使用您的Twitter凭据文件（请参阅身份验证方法)
运行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进行设置

通过在配置文件中添加以下内容来配置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\"]"
      }
    }
  }
}

重新启动克劳德桌面

身份验证方法

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：

在浏览器中登录推特
打开开发人员工具（F12）
转到应用程序选项卡>Cookie
复制以下值 auth_token, ct0，以及 twid 饼干
确保包括 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 <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

示例用法

请克劳德：

“在推特上搜索有关人工智能的推文”
“发一条推特说‘克劳德你好！’”
“从@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支持两种方法：

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
用户名/密码验证:
- 集 TWITTER_USERNAME 和 TWITTER_PASSWORD 在您的环境中
- 在某些情况下可能会遇到Cloudflare保护

Grok费率限制

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

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

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

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

故障排除

身份验证问题

Cookie身份验证问题

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

Cookie过期：推特Cookie通常在一段时间后过期。尝试通过注销并重新登录推特来刷新Cookie。
Cookie格式：确保您的Cookie格式正确，为具有正确域的JSON字符串数组。
所需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\"]"

凭据身份验证问题

如果您在用户名/密码验证方面遇到问题：

双因素身份验证：如果您的帐户启用了2FA，您需要提供 TWITTER_2FA_SECRET.
帐户锁定：登录尝试失败次数过多可能会锁定您的帐户。检查您的电子邮件以获取帐户验证请求。
验证码挑战：推特可能会出现验证码挑战，客户无法自动处理。

API身份验证问题

对于API身份验证问题：

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

操作错误

推特发布失败

如果你不能发布推文：

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

搜索问题

如果搜索不起作用：

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

Grok问题

如果Grok功能不起作用：

版本要求:
- Grok需要代理推特客户端v0.0.19 或更高
- 当前软件包使用v0.0.18实现基本功能
- 对于演示脚本，请使用 --use-local-agent-twitter-client 临时安装v0.0.19的标志
身份验证问题:
- Cookie格式：确保Cookie采用正确的JSON数组格式
- Cookie有效期：推特Cookie在一段时间后过期
- Cloudflare保护：用户名/密码身份验证可能被Cloudflare阻止
- 高级要求：Grok访问需要Twitter高级订阅
速率限制:
- 非高级帐户：每2小时25条消息
- 错误消息：“速率限制：您已达到限制…”
- 解决方案：等待费率限制重置或升级到高级帐户
环境文件位置:
- 对于演示脚本，请确保您的凭据在 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

设置

克隆存储库

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

安装依赖项

npm install

创建一个 .env 配置文件：

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

构建项目

npm run build

启动服务器

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

创建一个 .env 使用您的推特凭据进行文件
使用docker compose运行：

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Docker中的环境变量

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

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

持久日志

docker compose配置包括一个用于日志的卷挂载：

volumes:
  - ./logs:/app/logs

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

安全考虑

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

许可证

麻省理工学院