Skip to content
Back to search

x-use

Read-only X API v2 MCP server using official xurl OAuth, with structured tools for posts, users, search, threads, media, and credits.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/felixlark--x-use/badge.svg)](/listings/felixlark--x-use)

HTML

<a href="/listings/felixlark--x-use"><img src="/api/listings/felixlark--x-use/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/felixlark/x-use.git
cd x-use
npm ci
npm test

Run directly from the checkout:

X_USE_APP=your-xurl-app \
X_USE_USER=your-x-username \
node bin/x-use-mcp.js

The process speaks MCP over stdio; it is not intended to be used as a normal HTTP server.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 178 lines
  1. # X Use
  2. [![CI](https://github.com/felixlark/x-use/actions/workflows/ci.yml/badge.svg)](https://github.com/felixlark/x-use/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. **A read-only MCP server for the X API v2, using the official `xurl` OAuth client as the only credential source.**
  5. `X Use` exposes structured tools for posts, users, timelines, search, conversations, media metadata, and account/credit status. It does not manage a second token store and does not expose posting, reply, DM, follow, like, bookmark, delete, or media-upload tools.
  6. 中文说明见下方。
  7. ## Features
  8. | Tool | Purpose | X API |
  9. | --- | --- | --- |
  10. | `x_post` | Read a post by URL or ID, including author/media/references | `GET /2/tweets/{id}` |
  11. | `x_user` | Look up a user by username or numeric ID | `GET /2/users/by/username/{username}` / `GET /2/users/{id}` |
  12. | `x_user_posts` | Read a user's recent posts with pagination | `GET /2/users/{id}/tweets` |
  13. | `x_search` | Recent or full-archive search | `GET /2/tweets/search/recent` / `all` |
  14. | `x_thread` | Resolve `conversation_id` and read posts in a conversation | Post lookup + Search |
  15. | `x_media` | Read media metadata by media key | `GET /2/media/{media_key}` |
  16. | `x_status` | Verify authentication and read developer credits | `/2/users/me` + `/2/usage/credits` |
  17. All tool calls return JSON with a stable envelope:
  18. - `data` and `includes`: the relevant upstream X API payload
  19. - `pagination`: mapped `next_token`, `previous_token`, `newest_id`, and `oldest_id`
  20. - `meta`: tool, endpoint, upstream metadata, and `partial_errors`
  21. - `error.code`: `unauthenticated`, `forbidden`, `rate_limited`, `not_found`, `invalid_request`, or `unknown`
  22. ## Requirements
  23. - Node.js 20 or newer
  24. - Official [`xurl`](https://github.com/xdevplatform/xurl) with an authorised OAuth2 user
  25. - An X developer App with access to the endpoints you intend to use
  26. - Credits/entitlement for the corresponding X API calls
  27. The server reads X through `xurl` with `--auth oauth2`. It does **not** read `~/.xurl/auth.yml`, print tokens, or accept access tokens through MCP arguments.
  28. ## Quick start
  29. ```bash
  30. git clone https://github.com/felixlark/x-use.git
  31. cd x-use
  32. npm ci
  33. npm test
  34. ```
  35. Run directly from the checkout:
  36. ```bash
  37. X_USE_APP=your-xurl-app \
  38. X_USE_USER=your-x-username \
  39. node bin/x-use-mcp.js
  40. ```
  41. The process speaks MCP over stdio; it is not intended to be used as a normal HTTP server.
  42. ## Install for Codex
  43. The supplied installer creates a versioned local installation, atomically switches `current`, and links the bundled Skill into `~/.agents/skills/x-use`.
  44. ```bash
  45. ./scripts/install.sh
  46. ```
  47. On macOS the default MCP executable is:
  48. ```text
  49. $HOME/Library/Application Support/x-use/current/bin/x-use-mcp.js
  50. ```
  51. On Linux it is:
  52. ```text
  53. $HOME/.local/share/x-use/current/bin/x-use-mcp.js
  54. ```
  55. Register it with Codex using your own existing xurl app and OAuth2 username:
  56. ```bash
  57. codex mcp add x-use \
  58. --env X_USE_APP=your-xurl-app \
  59. --env X_USE_USER=your-x-username \
  60. -- "$HOME/Library/Application Support/x-use/current/bin/x-use-mcp.js"
  61. ```
  62. Use the Linux path shown above where applicable. Reload or restart the MCP connection after installation.
  63. ## Configuration
  64. | Variable | Required | Meaning |
  65. | --- | --- | --- |
  66. | `X_USE_APP` | Recommended | Registered app name in xurl |
  67. | `X_USE_USER` | Recommended | Existing OAuth2 username in xurl |
  68. | `X_USE_XURL_BIN` | No | Path to xurl; defaults to `xurl` on `PATH` |
  69. | `X_USE_TIMEOUT_MS` | No | Per-command timeout, 1–120 seconds |
  70. | `X_USE_INSTALL_ROOT` | No | Override the installer's application-data directory |
  71. | `X_USE_SKILLS_ROOT` | No | Override the installer's Skill root |
  72. The implementation always requests OAuth2 user context. It never silently falls back to OAuth1, app-only bearer, another user, or another provider.
  73. ## Example
  74. ```json
  75. {
  76. "name": "x_user_posts",
  77. "arguments": {
  78. "user": "@XDevelopers",
  79. "max_results": 5
  80. }
  81. }
  82. ```
  83. A successful result contains the X payload plus a pagination view:
  84. ```json
  85. {
  86. "ok": true,
  87. "data": ["..."],
  88. "includes": {"users": ["..."]},
  89. "pagination": {
  90. "result_count": 5,
  91. "next_token": "opaque-next-token",
  92. "previous_token": null,
  93. "newest_id": "...",
  94. "oldest_id": "..."
  95. },
  96. "meta": {
  97. "tool": "x_user_posts",
  98. "backend": "x_api_v2",
  99. "partial_errors": []
  100. }
  101. }
  102. ```
  103. ## Documentation
  104. - [API investigation](docs/INVESTIGATION.md): source-backed capability, auth, pricing, rate-limit, hosted MCP, and XChat notes
  105. - [Architecture](docs/ARCHITECTURE.md): backend choice, trust boundaries, upgrade and fallback paths
  106. - [Interfaces and implementation](docs/INTERFACES.md): tool contracts, call flow, envelopes, error mapping, and installer
  107. - [Contributing](CONTRIBUTING.md)
  108. - [Security policy](SECURITY.md)
  109. - [Support](SUPPORT.md)
  110. - [Changelog](CHANGELOG.md)
  111. ## Safety and boundaries
  112. - X Use is deliberately read-only. Write actions require a separate, explicit design and per-action authorization.
  113. - An MCP tool's absence is not evidence that an external action is unauthorized or authorized.
  114. - X API rate limits, account entitlement, and usage charges remain in force; this project does not buy credits or change billing.
  115. - `x_media` may return `forbidden` when the developer App is not enrolled in a required Project. Parent-post `includes.media` remains available through `x_post`.
  116. - XChat is not exposed: encrypted content additionally requires DM scopes, a Chat XDK, and client-held private keys.
  117. - Never put tokens, cookies, XChat PINs, private keys, or private account data in an issue, pull request, fixture, or log.
  118. ## Development
  119. ```bash
  120. npm ci
  121. npm test
  122. npm run check
  123. npm run check:live
  124. ```
  125. `npm test` is offline and covers parsing, pagination/field mapping, error classification, redaction, MCP tool discovery, resources, and mocked tool calls. `npm run check:live` performs a small read-only smoke test and therefore uses real X API credits.
  126. ## 中文概览
  127. X Use 是一个只读的 X API v2 MCP Server。它复用本机官方 `xurl` 的 OAuth2 会话,不保存第二份 token,也不暴露发帖、回复、DM、关注、点赞、书签、删除或媒体上传工具。
  128. 七个工具分别覆盖帖子、用户、用户帖子、搜索、会话、媒体元数据和认证/额度状态。返回使用统一的 `data`、`includes`、`pagination`、`meta` 信封;错误分为 `unauthenticated`、`forbidden`、`rate_limited`、`not_found`、`invalid_request` 和 `unknown`。
  129. 安装、Tool 参数、调用链和错误映射见 [接口与实现](docs/INTERFACES.md)。使用前需要 Node.js 20+、官方 `xurl` 和对应的 X API 权益;本项目的真实读取 smoke 会消耗实际 API credits。
  130. ## License
  131. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.