使用说明

X MCP服务器v2.0

用于X（Twitter）API v2的综合模型上下文协议（MCP）服务器 多用户OAuth 2.0+PKCE、加密令牌存储和自动令牌刷新。

🚀 v2.0中的新功能

✅ 多用户支持 -具有隔离令牌和会话的多个用户
✅ 双OAuth流 -环回（本地）+托管配对代码（远程/多用户）
✅ 加密令牌存储 -集成OS钥匙链的SQLite数据库
✅ 自动令牌刷新 -通过范围验证进行后台刷新
✅ 会话管理 -针对不同传输的安全会话处理
✅ 非浏览器支持 -无需通过配对代码访问浏览器即可工作

特性

✅ OAuth 2.0授权码+PKCE身份验证（两个流程）
✅ 具有每个用户令牌隔离的多用户支持
✅ 加密的本地令牌存储（AES-256+OS密钥链）
✅ 自动令牌刷新和持久化
✅ 范围验证和重新认证说明
✅ 具有重试/回退逻辑的速率限制
✅ 书签管理（列表、添加、删除）
✅ 推特创建（文本、媒体、回复、引用）
✅ 会话感知MCP资源
✅ 全面的错误处理和记录

设置

1.X开发人员帐户设置

创建一个 X开发人员帐户
在中创建新应用程序开发人员门户
配置OAuth 2.0设置：
- 应用程序权限：阅读和写作
- 应用程序类型：Web应用程序
- 回调URI: http://localhost:3000/callback （或您的自定义URI）
- 网站地址：必填（可以是占位符）
注意你的 客户端ID 和 客户端密钥

2.安装

# Clone or create the project directory
cd x-mcp
npm install
npm run build

3.环境设置

创建一个 .env 文件或导出环境变量：

export X_CLIENT_ID="your_client_id_here"
export X_CLIENT_SECRET="your_client_secret_here"
export X_REDIRECT_URI="http://localhost:3000/callback"  # Optional

4.身份验证

运行身份验证帮助程序以完成OAuth流程：

npm run auth
# or
node dist/auth-helper.js

这将：

打开浏览器到X的授权页面
启动本地回叫服务器
将授权码替换为令牌
将令牌保存到 ~/.x-mcp/tokens.json

快速开始

V2.0多用户服务器（推荐）

npm install
npm run build

# Set environment variables
export X_CLIENT_ID="your_client_id"
export X_CLIENT_SECRET="your_client_secret"

# Start multi-user server
npm start

身份验证流程

本地/单用户（环回）

# Via MCP tool call
{"method": "tools/call", "params": {"name": "auth/start", "arguments": {"mode": "loopback"}}}
# Opens browser for authorization

多用户/远程（托管配对）

# Enable hosted mode
export X_HOSTED_MODE="true"
export X_BASE_URL="https://yourapp.com"

# Via MCP tool call  
{"method": "tools/call", "params": {"name": "auth/start", "arguments": {"mode": "hosted"}}}
# Returns pairing code + login URL

# Check status
{"method": "tools/call", "params": {"name": "auth/status", "arguments": {"pairing_code": "ABC12345"}}}

旧版V1.0服务器

npm run start:legacy
# or
node dist/index.js

MCP工具

服务器提供以下工具：

`bookmarks.list`

列出支持分页的用户书签。

参数：

user_id （可选）：用户ID（默认为经过身份验证的用户）
max_results （可选）：每页最大结果数（1-100，默认值：10）
pagination_token （可选）：下一页结果的标记

例子：

{
  "tweets": [
    {
      "id": "1234567890",
      "text": "Great tweet content...",
      "created_at": "2023-01-01T00:00:00.000Z",
      "author_id": "987654321",
      "public_metrics": {
        "retweet_count": 5,
        "like_count": 10,
        "reply_count": 2,
        "quote_count": 1
      }
    }
  ],
  "nextToken": "next_page_token"
}

`bookmarks.add`

在书签中添加推文。

参数：

tweet_id （必填）：要添加书签的推文的ID
user_id （可选）：用户ID（默认为经过身份验证的用户）

退货： { "ok": true }

`bookmarks.remove`

从书签中删除推文。

参数：

tweet_id （必填）：要从书签中删除的推文的ID
user_id （可选）：用户ID（默认为经过身份验证的用户）

退货： { "ok": true }

`tweet.create`

创建一条新推文。

参数：

text （必填）：推特文本内容（最多280个字符）
media_ids （可选）：要附加的媒体ID数组
reply （可选）：对象 in_reply_to_tweet_id 用于回复
quote_tweet_id （可选）：要引用的推文的ID

例子：

{
  "id": "1234567890",
  "createdAt": "2023-01-01T00:00:00.000Z"
}

MCP资源

`mcp://x/user/me`

当前已验证的X用户信息：

{
  "id": "123456789",
  "username": "example_user",
  "name": "Example User"
}

`mcp://x/bookmarks/latest`

上次获取的带有分页标记的书签页面：

{
  "tweets": [...],
  "nextToken": "pagination_token"
}

所需范围

服务器需要以下X个API作用域：

bookmark.read 或 bookmarks.read -阅读书签
bookmarks.write -修改书签
tweet.write -发布推文
tweet.read -阅读推文（用于推文创建回复）
users.read -读取用户信息
offline.access -刷新令牌支持

如果缺少作用域，服务器将提供重新身份验证指令。

速率限制

服务器自动处理X个API速率限制：

✅ 对429/5xx响应进行指数回退的检索
✅ 倒像 x-rate-limit-* 智能节流接头
✅ 当限制较低时，显示MCP通知
✅ 适应API的实际限制（不是硬编码限制）

当前典型限制（可能因计划而异）：

获取书签：每15分钟约180个请求
发布/删除书签：每15分钟约50个请求
POST推文：每15分钟约300个请求

文件结构

src/
├── index.ts          # Main MCP server
├── auth.ts           # OAuth 2.0 + PKCE implementation
├── auth-helper.ts    # Interactive authentication flow
├── x-client.ts       # X API client with bookmarks/tweets
├── http-client.ts    # HTTP client with retry/rate limiting
├── storage.ts        # Token persistence
└── types.ts          # TypeScript type definitions

脚本

npm run build          # Compile TypeScript
npm start              # Start v2.0 multi-user server  
npm run start:legacy   # Start v1.0 legacy server
npm run auth           # Interactive OAuth helper (legacy)
npm test               # Run comprehensive test suite
npm run dev            # Development mode
npm run watch          # Watch mode compilation

配置

V2.0环境变量：

X_CLIENT_ID -X应用程序客户端ID（必需）
X_CLIENT_SECRET -X应用程序客户端机密（必需）
X_REDIRECT_URI -OAuth重定向URI（默认值： http://127.0.0.1:3000/auth/x/cb)
X_HOSTED_MODE -启用托管配对模式(true/false)
X_BASE_URL -托管模式的基本URL（例如。， https://yourapp.com)
X_MCP_ENCRYPTION_KEY -手动加密密钥（base64，可选）

存储位置：

V2.0数据库： ~/.mcp/x/tokens.db （带加密的SQLite）
V1.0令牌： ~/.x-mcp/tokens.json （传统JSON格式）
加密密钥： OS钥匙扣或 ~/.mcp/x/.encryption_key

错误处理

服务器为以下对象提供详细的错误消息：

❌ 缺少身份验证/令牌
❌ 带有重新身份验证指令的作用域不足
❌ 请求ID出现API错误（处于调试模式）
❌ 违反速率限制并提供重试指导
❌ 具有重试逻辑的网络错误

测试

综合测试套件

npm test  # Runs all tests including encryption, database, OAuth flows

手动E2E测试（V2.0）

启动服务器: npm start
环回身份验证：呼叫 auth/start 随着 mode: "loopback"
完成OAuth：打开返回的URL，授权
测试书签: bookmarks.list, bookmarks.add, bookmarks.remove
测试推文: tweet.create

多用户测试（V2.0）

启用托管模式：设置 X_HOSTED_MODE=true, X_BASE_URL
开始配对：呼叫 auth/start 随着 mode: "hosted"
完整身份验证：使用配对代码访问登录URL
检查状态：呼叫 auth/status 带配对码
会话测试：在后续调用中包含会话上下文

传统测试（V1.0）

认证: npm run auth
启动旧服务器: npm run start:legacy
测试工具：使用现有的MCP工具

故障排除

身份验证问题

验证X_CLIENT_ID和X_CLIENT_SECRET是否正确
检查重定向URI是否与您的应用程序配置匹配
确保您的X应用程序具有正确的权限（读取和写入）

范围问题

重新运行 npm run auth 获取更新的范围
检查您的X应用程序是否配置了所需的权限

利率限制问题

服务器将自动重试并回退
检查日志以获取速率限制信息
考虑X开发人员帐户的计划限制

令牌问题

令牌过期时会自动刷新
V2.0：检查数据库 ~/.mcp/x/tokens.db，跑 npm test 用于诊断
V1.0：删除 ~/.x-mcp/tokens.json 并在需要时重新进行身份验证

📚 详细文件

有关新的多用户OAuth系统、体系结构和高级用法的全面文档，请参阅：

自述-MULTIUSER.md -使用以下内容完成v2.0文档：

🏗️ 详细的架构概述
🔐 安全实施细节
🗄️ 数据库模式和设计
📡 完整的API参考
🧪 高级测试场景
🛠️ 开发和扩展指南

使用说明

X MCP服务器v2.0

🚀 v2.0中的新功能

特性

设置

1.X开发人员帐户设置

2.安装

3.环境设置

4.身份验证

快速开始

V2.0多用户服务器（推荐）

身份验证流程

本地/单用户（环回）

多用户/远程（托管配对）

旧版V1.0服务器

MCP工具

bookmarks.list

bookmarks.add

bookmarks.remove

tweet.create

MCP资源

mcp://x/user/me

mcp://x/bookmarks/latest

所需范围

速率限制

文件结构

脚本

配置

V2.0环境变量：

存储位置：

错误处理

测试

综合测试套件

手动E2E测试（V2.0）

多用户测试（V2.0）

传统测试（V1.0）

故障排除

身份验证问题

范围问题

利率限制问题

令牌问题

📚 详细文件

相关 MCP

内存存储检索服务器

待办事项管理服务器

Stitch MCP 集成包

模型上下文协议库

模型上下文协议服务器

Spotify控制服务

`bookmarks.list`

`bookmarks.add`

`bookmarks.remove`

`tweet.create`

`mcp://x/user/me`

`mcp://x/bookmarks/latest`