xippios-x

Typed Python client, MCP server and FastAPI routes for X API v2, part of the xippios SDK family. Names and semantics follow the upstream documentation; every response carries release metadata (source, endpoint, retrieved_at, published_at, vintage).

Install

uv add xippios-x            # client only
uv add "xippios-x[mcp]"     # + MCP server
uv add "xippios-x[http]"    # + FastAPI router

Set X_API_KEY in the environment to your X app's Bearer Token, which X also calls the App only Access Token (Developer Console, Keys and tokens), not the console's API Key, the OAuth 1.0a consumer key. Nothing is read from files.

30-second example

from xippios.x import tasks

users = tasks.lookup_users(["USDA", "FAO"])  # 0.010 USD a user found
usda = next(user for user in users.data.data if user.username == "USDA")

page = tasks.get_user_posts(usda.id, max_results=10)  # 0.005 USD a post returned
for post in page.data.data or []:
    print(post.created_at, post.public_metrics.like_count, post.text)
print(page.meta.retrieved_at, page.meta.request, page.data.meta.result_count)

older = tasks.get_user_posts(usda.id, pagination_token=page.data.meta.next_token)

Every task returns one page as X sends it, in result.data; a call that returns data spends X credits at the prices of X's pricing page, which each task's docstring names (the page states none for get_usage). Paging is the caller's, with the next_token of the previous page's meta. Underneath the tasks, xippios.x.api wraps nine X API v2 operations one page at a time (users by username, posts by id, a user's posts, post counts over the archive, recent search, post counts over the last seven days, a List's posts, a List's members and the project's usage).

MCP

{
  "mcpServers": {
    "x": {
      "command": "uvx",
      "args": ["--from", "xippios-x[mcp]", "xippios-x-mcp"],
      "env": { "X_API_KEY": "..." }
    }
  }
}

xippios-x-mcp serves stdio; --http serves streamable HTTP instead. Tools are read-only and named x_<verb>_<noun>; every call that returns data spends X credits, and each tool's description gives its price (the pricing page states none for x_get_usage). A tool returns one page, which its result cap holds whole for Latin-script text: up to 100 posts in 128,000 bytes, 100 users in 160,000, and 64 KB for the counts, which a month of hourly buckets fits. A page of mostly non-Latin text, or minute counts over more than about 14 hours, can be cut, with a note on how to see the rest.

Status

Prices are those of X's pricing page in the snapshot of 2026-10-29 (docs/upstream/pages/pricing.md); a post or user read again the same UTC day is not billed again, a counts request always is.

Upstream terms and attribution

Data comes from X API v2 (https://x.com) under the X Developer Agreement and the X Developer Policy, which bind every app that uses it; this package adds no rights to it. Documentation snapshot and its attribution: docs/upstream/FETCHED.md.

Licence

Apache-2.0. See LICENSE.