X (Twitter) API

Read-only access to X content via five MCP tools. Use for sentiment on tickers, exec announcements, launches, event tracking, and qualitative research alongside SEC/market data.

Not for single-post URL lookups. If the user hands you a specific X post URL and just wants its text or context, use web_fetch on the URL, no vault, no auth, no rate limit. Reach for this skill when the task is search, aggregation, or thread traversal.

Auth

Every tool requires a bearer_token. Read it once per code block from the vault:

from vault import get
token = get("X_BEARER_TOKEN")

If token is None or empty, the user hasn't added it yet. For the setup walkthrough and per-error fixes, see TROUBLESHOOTING.md.

Tools at a glance

The primary use case is search, the first two tools are what you'll reach for most.

Tool	Use for	Page size	Notes
search_posts	Posts from the last ~7 days	default 10, max 100	Default choice. Query ≤512 chars.
search_all_posts	Posts older than 7 days (back to 2006)	default 10, max 500	Paid-tier X plan only. Query ≤1024 chars.
get_conversation	Reply thread to a root tweet	default 50, max 100	Uses recent search, thread must be ≤7 days old. Root tweet not included.
get_user_by_username	A user profile + metrics	,	Handle without @, ≤15 chars.
get_tweet_by_id	Hydrate a single post (mainly to find its conversation_id before get_conversation)	,	For a one-off URL the user already has, prefer web_fetch.

Examples

Recent sentiment on a ticker

res = search_posts(
    query="$NVDA -is:retweet lang:en",
    bearer_token=token,
    max_results=100,
)
posts = res["posts"]
posts.sort(key=lambda p: p["public_metrics"].get("impression_count", 0), reverse=True)
for p in posts[:10]:
    print(p["author"]["username"], p["public_metrics"].get("like_count"), p["text"][:140])