Py X MCP

X（推特）API客户端

这是一款用于与X（Twitter）API集成的Python客户端。您可以通过MCP从AI助手（如Claude、Gemini等）操作X API。

这个库的作用

这个库是 X API 的客户端尽管它也作为MCP（可能是指某种特定协议或系统，如“管理控制协议”等，具体需根据上下文确定）服务器的功能，但其名称 x_client 这意味着它是一个用于X（Twitter）服务器的客户端。

graph TD
    A["AI Agent
Claude / Gemini / Codex etc."] -->|MCP Protocol over stdio| B["MCP Server Entrypoint
(x_client.integrations.mcp_server)"]

    %% Subgraph: Stabilize parsing by separating ID and display name
    subgraph x_client_library["x_client Library — Single Python Process"]
        B -->|Internal Call| C["XMCPAdapter"]
        C -->|Internal Call| D["Service Layer
(PostService, MediaService)"]
        D -->|Internal Call| E["Client Layer
(TweepyClient)"]
        D -->|Internal Call| F["Client Layer
(OriginalClient ...future)"]
    end

    E -->|X API HTTP / REST| G["X Server
Twitter (X)"]
    F -->|X API HTTP / REST| G["X Server
Twitter (X)"]

    style B fill:#e1f5ff
    style C fill:#e1f5ff
    style D fill:#e1f5ff
    style E fill:#e1f5ff
    style F fill:#e1f5ff
    style A fill:#fff4e6
    style G fill:#f3e5f5

明确角色分工：

• AI代理（MCP客户端）像Claude Code、Claude Desktop、Gemini这样的AI助手。
• MCP服务器此库提供的与MCP协议兼容的服务器。
• X 客户端这个库的核心功能。X API 的客户端。
• X服务器Twitter/X 的主要服务器。

换句话说，这个库有两面性：

1. 从MCP（可能指某特定概念、公司或项目，具体需根据上下文确定，此处直译为“从MCP的角度”）的角度它起着MCP（主控制面板/多点控制单元）的作用 服务器 为人工智能代理提供工具。
2. 从X API的角度来看它充当X API 客户 与X服务器进行通信。

也可以在不使用MCP的情况下将X API作为库来使用（见README.md文件底部）。

要求

• Python 3.11 或更高版本
• X（Twitter）开发者账号和一套API密钥
• 包管理工具 紫外线 （推荐）

与MCP（模型上下文协议）的使用

您可以从AI助手（如Claude Code、Claude Desktop、codex-cli、Gemini等）中操作X API。

🚀 推荐设置：使用uvx进行统一执行

通过使用 uvx 在所有环境中，您都可以获得自动依赖管理，并始终保持最新状态。

配置

在每个AI工具的MCP配置文件中描述以下内容：

TOML 格式（Codex-CLI 等）:

• 发布在 PyPI 上

[mcp.servers.x_client]
command = "uvx"
args = ["--from", "pyx-mcp", "x-mcp-server"]

[mcp.servers.x_client.env]
X_API_KEY = "your-api-key"
X_API_SECRET = "your-api-secret"
X_ACCESS_TOKEN = "your-access-token"
X_ACCESS_TOKEN_SECRET = "your-access-token-secret"

• 来自GitHub的最新动态

[mcp.servers.x_client]
command = "uvx"
args = ["--from", "git+https://github.com/hellocybernetics/pyX-MCP", "x-mcp-server"]

[mcp.servers.x_client.env]
X_API_KEY = "your-api-key"
X_API_SECRET = "your-api-secret"
X_ACCESS_TOKEN = "your-access-token"
X_ACCESS_TOKEN_SECRET = "your-access-token-secret"

JSON 格式（Claude 代码、Gemini CLI 等）:

• 发布在 PyPI 上

{
  "mcpServers": {
    "x_client": {
      "command": "uvx",
      "args": ["--from", "pyx-mcp", "x-mcp-server"],
      "env": {
        "X_API_KEY": "your-api-key",
        "X_API_SECRET": "your-api-secret",
        "X_ACCESS_TOKEN": "your-access-token",
        "X_ACCESS_TOKEN_SECRET": "your-access-token-secret"
      }
    }
  }
}

• 来自GitHub的最新消息

{
  "mcpServers": {
    "x_client": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/hellocybernetics/pyX-MCP", "x-mcp-server"],
      "env": {
        "X_API_KEY": "your-api-key",
        "X_API_SECRET": "your-api-secret",
        "X_ACCESS_TOKEN": "your-access-token",
        "X_ACCESS_TOKEN_SECRET": "your-access-token-secret"
      }
    }
  }
}

重要的设置完成后，请完全重启您的AI工具。

操作检查

向您的AI助手提出以下问题：

"List the available X API tools"

或者

"Post 'Hello from MCP!'"

UVX设置的优势

• ✅ 环境独立无需Node.js，仅需Python环境即可运行
• ✅ 自动依赖管理uv 自动构建并缓存虚拟环境
• ✅ 始终保持最新： --from pyx-mcp 自动从PyPI获取最新版本
• ✅ 统一配置所有AI助手的配置方法相同

______________________________________________________________________

提供的功能

以下工具可通过MCP获取：

发帖功能

• 创建帖子纯文本帖子、带图片/视频的帖子、回复、引用帖子
• 删除帖子删除一条帖子
• 获取帖子通过ID获取帖子
• 创建线程自动将长文本拆分为帖子线程

转发功能

• 转发帖子转发帖子
• 撤销转发取消转发

搜索功能

• 搜索最近帖子搜索过去7天内的帖子（包含作者信息）

媒体上传

• 上传图片上传一张图片（JPEG/PNG/WebP/GIF格式，最大5MB）
• 上传视频上传视频（MP4格式，最大512MB，支持分片上传）

身份验证和状态检查

• 获取授权状态获取身份验证状态和速率限制信息

使用示例

You: "Post 'Hello from Claude via MCP!'"

Claude: Using the create_post tool...
       Post completed! Post ID: 1234567890

You: "Search for recent posts about 'MCP protocol'"

Claude: Using the search_recent_posts tool...
       Found 3 posts:
       1. @user1: I tried using MCP...
       2. @user2: Model Context Protocol is...

建筑学

AI Assistant ↔ MCP Server (stdio) ↔ XMCPAdapter ↔ Service Layer ↔ X API

错误处理

• 配置错误缺少身份验证信息。请检查 .env 以及环境变量。
• 认证错误令牌已过期。请重新运行OAuth流程。
• 速率限制超出已达到速率限制。请参考（相关说明）稍后再试 reset_at。
• 媒体处理超时/失败等待视频处理完成超时。请调整 timeout 以及视频质量。

故障排除

• 缺少凭据检查环境变量 echo $X_API_KEY检查是否 .env 以……方式保存 0o600。
• 无效的令牌重新运行OAuth流程以更新身份验证信息。
• 视频超时扩展 timeout 的 upload_video 或者使用（某种方式）重新编码 ffmpeg。

______________________________________________________________________

作为库使用

它也可以直接从Python代码中调用。

安装

uv add pyx-mcp

如何获取认证信息

要使用这个库，您需要从您的X（Twitter）开发者帐户中获取以下四件认证信息。

1. 访问X开发者门户：

- 首选 https://developer.x.com/en/portal/dashboard 的中文翻译可以是：“https://developer.x.com/开发者门户/仪表盘”。不过，实际翻译时，网址通常保持原样，不进行翻译，因为网址是特定的网络地址，直接使用即可。所以，如果仅从翻译的角度来看，可以表述为“开发者门户网站的仪表盘（网址：https://developer.x.com/en/portal/dashboard）”，但网址本身无需翻译 并登录。

1. 选择或创建一个应用程序：

- 选择一个现有应用程序或创建一个新应用程序。

1. 检查密钥和令牌：

- 在应用程序仪表板上，转到“密钥和令牌”选项卡。

1. 生成并设置权限：

- API密钥和密钥在“消费者密钥”部分进行检查或重新生成。 - 访问令牌和密钥在“身份验证令牌”部分，生成一个访问令牌和密钥 读与写 权限。

将这些检索到的值设置为环境变量，或者 .env 以下描述的文件。

设置认证信息

使用环境变量或（其他方式）设置认证信息 .env 文件：

export X_API_KEY="your_api_key"
export X_API_SECRET="your_api_secret"
export X_ACCESS_TOKEN="your_access_token"
export X_ACCESS_TOKEN_SECRET="your_access_token_secret"
export X_BEARER_TOKEN="your_bearer_token"  # for v2 API (optional)

或者在一个 .env 文件（放置在项目根目录）：

X_API_KEY=your_api_key
X_API_SECRET=your_api_secret
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret
X_BEARER_TOKEN=your_bearer_token

.env 自动设置为 0o600 （所有者仅读/写）。 .env* 是 .gitignored

______________________________________________________________________

基本用法

from x_client.config import ConfigManager
from x_client.factory import XClientFactory
from x_client.services.post_service import PostService
from x_client.services.media_service import MediaService

# 1. Load authentication information
config = ConfigManager()
client = XClientFactory.create_from_config(config)

# 2. Initialize the service layer
post_service = PostService(client)
media_service = MediaService(client)

# 3. Create a post
post = post_service.create_post(text="Hello from x_client!")
print(f"Post created: {post.id}")

# 4. Post with an image
from pathlib import Path
media_result = media_service.upload_image(Path("image.png"))
post = post_service.create_post(
    text="Check out this image!",
    media_ids=[media_result.media_id]
)

# 5. Post a long thread
thread = post_service.create_thread(
    '''Python 3.11 highlights... (long text)''',
    chunk_limit=200,
)
for idx, segment_post in enumerate(thread.posts, start=1):
    print(f"Segment {idx}: {segment_post.id}")
if not thread.succeeded:
    print("Thread failed", thread.error)

# 6. Repost operation
repost_state = post_service.repost_post(post.id)
print("Reposted:", repost_state.reposted)

undo_state = post_service.undo_repost(post.id)
print("Repost removed:", not undo_state.reposted)

# 7. Search with author information
search_results = post_service.search_recent(
    "from:twitterdev",
    expansions=["author_id"],
    user_fields=["username", "verified"],
    post_fields=["created_at"],
)
for item in search_results:
    author = item.author.username if item.author else "unknown"
    print(author, item.text)

通过MCP适配器使用（上述API的简化版）

它也可以直接从非MCP客户端调用：

from x_client.integrations.mcp_adapter import XMCPAdapter

adapter = XMCPAdapter()  # Authentication information is automatically loaded by ConfigManager

post = adapter.create_post({"text": "Hello from MCP!"})
print(post)

media = adapter.upload_image({"path": "/path/to/image.png"})
adapter.create_post({"text": "Image post", "media_ids": [media["media_id"]]})

日志记录和可观测性

PostService 内置了结构化日志记录和事件钩子：

import logging
from x_client.config import ConfigManager
from x_client.factory import XClientFactory
from x_client.services.post_service import PostService

logging.basicConfig(level=logging.INFO)

client = XClientFactory.create_from_config(ConfigManager())

def metrics_hook(event: str, payload: dict[str, object]) -> None:
    # Integration point for Prometheus / OpenTelemetry, etc.
    print("metrics", event, payload)

post_service = PostService(client, event_hook=metrics_hook)
post_service.create_post("observability ready!")

事件钩子将成功和失败的情况合并到一个回调中，从而便于发送指标并与分布式追踪系统进行集成。

______________________________________________________________________

在开发环境中的使用

设置

uv sync

这将创建 x-mcp-server 命令输入（或“指令在”） .venv/bin/。

使用本地路径运行MCP服务器

直接运行开发中的MCP服务器：

{
  "mcpServers": {
    "x-client": {
      "command": "/absolute/path/to/twitter/.venv/bin/x-mcp-server",
      "env": {
        "X_API_KEY": "your-api-key",
        "X_API_SECRET": "your-api-secret",
        "X_ACCESS_TOKEN": "your-access-token",
        "X_ACCESS_TOKEN_SECRET": "your-access-token-secret"
      }
    }
  }
}

Alternative methods (click to expand)

方法2：直接使用紫外线

{
  "mcpServers": {
    "x-client": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/twitter", "python", "-m", "x_client.integrations.mcp_server"],
      "env": {
        "X_API_KEY": "your-api-key",
        "X_API_SECRET": "your-api-secret",
        "X_ACCESS_TOKEN": "your-access-token",
        "X_ACCESS_TOKEN_SECRET": "your-access-token-secret"
      }
    }
  }
}

方法3：启动器脚本

{
  "mcpServers": {
    "x-client": {
      "command": "/absolute/path/to/twitter/scripts/run_mcp_server.sh",
      "env": { "X_API_KEY": "...", "X_API_SECRET": "...", "X_ACCESS_TOKEN": "...", "X_ACCESS_TOKEN_SECRET": "..." }
    }
  }
}

重要的替换 /absolute/path/to/twitter 附上实际的项目路径。

______________________________________________________________________

在命令行界面（CLI）中的使用

你可以轻松地通过命令行发布内容，使用 examples/create_post.py。

基本用法

# Text only
python examples/create_post.py "Hello from x_client!"

# With image
python examples/create_post.py "Check out this image!" --image path/to/image.png

# With video (max 512MB, chunked upload supported)
python examples/create_post.py "Check out this video!" --video path/to/video.mp4

# Use .env from a different path
python examples/create_post.py "Hello with custom env" --dotenv /secure/path/.env

发帖（或“创建主题帖”）

# Long thread post (auto-split with chunk_limit=180)
python examples/create_post.py "Long form update..." --thread --chunk-limit 180

# Post a thread from a file (assuming UTF-8 text)
python examples/create_post.py --thread-file docs/thread_draft.txt

# Example of a long Japanese thread (break lines appropriately under 280 characters)
python examples/create_post.py --thread-file examples/long_thread_ja.txt --chunk-limit 180

# Example of a long English thread (maintaining sentence breaks)
python examples/create_post.py --thread-file examples/long_thread_en.txt --chunk-limit 240

# Wait 8 seconds between each post to avoid rate limits
python examples/create_post.py --thread-file examples/long_thread_en.txt --segment-pause 8

# Choose a split strategy (simple | sentence | paragraph)
python examples/create_post.py --thread-file examples/long_thread_en.txt \
  --chunk-limit 240 --split-strategy sentence

其他业务/操作

# Delete the first tweet of a failed thread (used to resolve duplicate errors)
python examples/create_post.py --delete 1234567890123456789

# Repost / Undo repost
python examples/create_post.py --repost 1234567890
python examples/create_post.py --undo-repost 1234567890

针对特定语言的考虑因素

• 日本（人）如果存在大量全角字符，填充至280个字符的限制可能会使阅读变得困难，因此请保持（简洁/不要过度填充） --chunk-limit 将每个短语的块保持在大约150-200个字符左右。此外，由于在标点符号后立即拆分可能会破坏上下文，因此在文本文件的一侧，为每个段落插入一个空行是安全的。

• 英语当包含网址或表情符号时，Twitter将其计为23个字符，因此设置 --chunk-limit 留有余地。如果你在每个句子后都加上换行，那么在拆分后阅读起来会更容易。

笔记

• 当转发一个帖子时，如果在24小时内发布完全相同的内容，你会收到一条（警告/限制等，具体根据上下文确定） 重复内容 由于X的规格导致的错误。请删除之前发布的帖子或在文本中添加一个唯一短语，如时间戳。

• 如果在短时间内连续发布内容，X API 可能会返回 HTTP 429（请求过多）错误。此库可以检测到这一点 RateLimitExceeded 并根据（情况）等待 x-rate-limit-reset 在重试之前，请检查响应头，但如果遇到429状态码，请等待2-3分钟后重新执行命令。设置（此处“Setting”可能是一个不完整的句子或标题，根据上下文，可以翻译为“设置（相关参数/选项）”或保持原样以符合特定语境，若单独使用，则可译为“设置”） --segment-pause 将延迟调整到大约5到10秒，可以更容易地提前避免429错误。

______________________________________________________________________

测试

# Test MCP server operation
uv run python scripts/test_mcp_server.py

# Unit tests
uv run pytest tests/unit/test_mcp_adapter.py -v

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=x_client --cov-report=html

# Verbose mode
uv run pytest -v

# Specific test file
uv run pytest tests/unit/test_tweepy_client.py

______________________________________________________________________

主要特点

• 双客户端配置：用于帖子的tweepy.Client（v2），用于媒体的tweepy.API（v1.1）
• 使用（某种方法/技术）实现安全的认证信息管理 .env 以及OAuth流程集成
• 高级API，带 PostService / MediaService
• 长篇帖子发布工具和自动回复链构建
• 重新发布/撤销API和MCP工具
• 支持在搜索API中指定扩展/字段并解析作者信息
• 服务层内置的结构化日志记录和事件钩子
• 通过MCP（模型上下文协议）集成实现AI助手的操作

______________________________________________________________________

支持

请通过问题报告或拉取请求的方式报告错误和改进建议。有关项目政策和设计的详细信息，请参阅 docs/ 并根据需要添加评论。