twikit-server

Lightweight HTTP API server for Twitter/X, powered by twikit. Exposes Twitter functionality as a local JSON API — read timelines, search tweets, post, like, retweet, bookmark, and look up users.

Features

• Timeline (Following / For You / merged)
• Tweet lookup, search, and compose
• Like, retweet, bookmark
• User profile and user tweets
• Automatic cookie persistence and retry on connection errors
• OpenClaw skill for AI agent integration

Installation

pip install twikit-server

Or from source:

git clone https://github.com/tang-hi/twikit_server.git
cd twikit-server
pip install -e .

Cookie Setup

twikit-server authenticates using browser cookies. The easiest way to export them is with the Cookie-Editor browser extension (available for Chrome, Firefox, and Edge):

1. Install Cookie-Editor.
2. Go to x.com and log in.
3. Click the Cookie-Editor icon in the toolbar.
4. Click Export (bottom-right) → JSON — cookies are copied to your clipboard.
5. Paste into a file and save as cookies.json in your working directory.

That's it. If you prefer not to install an extension, you can also manually copy cookies from DevTools (F12 → Application → Cookies → https://x.com).

Configuration

Variable	Default	Description
COOKIES_FILE	./cookies.json	Path to the cookies JSON file
HOST	0.0.0.0	Address to bind
PORT	19816	Port to listen on

Usage

twikit-server
# or
python -m twikit_server.server
# or with env vars
PORT=8080 COOKIES_FILE=~/my-cookies.json twikit-server

API Endpoints

Method	Path	Params / Body	Description
GET	/timeline	?type=following|foryou&count=20	Get timeline tweets
GET	/tweet/{id}		Get a single tweet by ID or URL
GET	/search	?q=keyword&sort=Latest&count=20	Search tweets
POST	/tweet	{"text": "...", "reply_to": "id"}	Create a tweet
POST	/tweet/{id}/like		Like a tweet
POST	/tweet/{id}/retweet		Retweet
POST	/tweet/{id}/bookmark		Bookmark a tweet
GET	/user/{username}		Get user profile
GET	/user/{username}/tweets	?count=20	Get user's tweets

Examples

# Get latest 5 tweets from Following timeline
curl http://localhost:19816/timeline?type=following&count=5

# Look up a tweet
curl http://localhost:19816/tweet/1234567890

# Search
curl http://localhost:19816/search?q=python&count=10

# Post a tweet
curl -X POST http://localhost:19816/tweet \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello from twikit-server!"}'

# Get user profile
curl http://localhost:19816/user/elonmusk

Response Format

Tweet objects are returned as JSON:

{
  "id": "1234567890",
  "text": "Hello world",
  "created_at": "2026-01-15 10:30:00",
  "user": {
    "name": "Example User",
    "screen_name": "example",
    "profile_image_url": "https://pbs.twimg.com/..."
  },
  "media": [
    {"type": "photo", "url": "https://pbs.twimg.com/..."}
  ],
  "favorite_count": 42,
  "retweet_count": 7,
  "reply_count": 3,
  "bookmark_count": 1,
  "view_count": 1500,
  "favorited": false,
  "bookmarked": false,
  "quote": null,
  "in_reply_to": null
}

OpenClaw Skill

twikit-server ships with an OpenClaw skill so AI agents can browse and interact with Twitter directly.

Install the skill

Copy (or symlink) the skill/ directory into your OpenClaw skills folder:

# Option A: symlink
ln -s /path/to/twikit-server/skill ~/.openclaw/workspace/skills/twikit-server

# Option B: copy
cp -r /path/to/twikit-server/skill ~/.openclaw/workspace/skills/twikit-server

Usage

1. Start the server: twikit-server
2. In OpenClaw, ask the agent anything Twitter-related — it will automatically use the skill to call the API via curl.

The skill provides instructions for all 9 endpoints (timeline, tweet lookup, search, post, like, retweet, bookmark, user profile, user tweets) with full response format documentation in references/response-format.md.

License

MIT