Skip to content
Back to search

nitter

Self-hosted, read-only X data gateway for AI agents: REST, MCP and Skills, with a privacy-friendly web front end

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xiaoy233--nitter/badge.svg)](/listings/xiaoy233--nitter)

HTML

<a href="/listings/xiaoy233--nitter"><img src="/api/listings/xiaoy233--nitter/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/xiaoY233/nitter.git && cd nitter
docker build -t vuldocker/nitter:latest .
# or use the image published by CI: docker pull ghcr.io/xiaoy233/nitter:latest

cp nitter.example.conf nitter.conf     # set [Api] enabled = true, redisHost = "nitter-redis"
cp /path/to/sessions.jsonl .           # X account sessions
echo "NITTER_API_TOKENS=me:$(openssl rand -hex 24)" > .env
# uncomment the `environment` block in compose.yml, then:
docker compose up -d

Check it:

curl http://127.0.0.1:8080/api/v1/health
curl -H "Authorization: Bearer <secret>" \
  "http://127.0.0.1:8080/api/v1/users/jack?format=markdown"

`<secret>` is the part of the token after the colon. Open `http://127.0.0.1:8080` in a browser for the web pages. The full walk-through, including building from source and systemd, is in [docs/deployment.md](docs/deployment.md).

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 · 134 lines
  1. # Nitter Agent API
  2. **English** | [简体中文](README.zh-CN.md)
  3. A self-hosted, read-only gateway that lets AI agents read public X (Twitter)
  4. data. One set of tools is served over **REST**, **MCP** and agent **Skills**,
  5. and Nitter's web front-end stays alongside it for people.
  6. ![The home page](docs/images/home.png)
  7. ```
  8. agent (Claude Code, Codex, pi, DeepSeek Harness, ...)
  9. │ MCP (Streamable HTTP) / REST / Skills
  10. ▼
  11. Nitter Agent API ──► Redis cache ──► X (your own account sessions)
  12. ```
  13. ## What it does
  14. Seven read-only tools, available through `POST /mcp` and `/api/v1/...`:
  15. | Tool | Purpose |
  16. |---|---|
  17. | `get_user` | Profile and counts |
  18. | `get_user_timeline` | One account's tweets, replies, media or articles |
  19. | `get_tweet` | One tweet, by id or URL |
  20. | `get_thread` | A tweet with its ancestors, continuation and replies |
  21. | `search_tweets` | Keyword, author and date search |
  22. | `search_users` | Find accounts |
  23. | `get_user_connections` | Followers and following |
  24. - **Built for agents.** Compact Markdown output by default, JSON on request,
  25. uniform pagination, stable error codes, and tweet text fenced as untrusted
  26. content to blunt prompt injection.
  27. - **Read-only.** There is no write, post or DM tool.
  28. - **Your own X sessions.** It reads X's web endpoints through the accounts you
  29. provide (see [docs/sessions.md](docs/sessions.md)). No official API key.
  30. - **Protected.** Bearer tokens, per-token rate limits, Origin checks, and a
  31. Redis cache that keeps repeated questions off your session quota.
  32. - **Self-describing.** `GET /api/v1/openapi.json` and `GET /llms.txt` list the
  33. tools for any client.
  34. - **Disabled by default.** Without `[Api] enabled = true` the server behaves as
  35. the plain Nitter web front-end.
  36. - **Prebuilt images.** CI publishes a multi-arch image to
  37. `ghcr.io/xiaoy233/nitter` when a version tag (`v*`) is pushed; it
  38. may need to be made public once (see
  39. [docs/deployment.md](docs/deployment.md#published-images)).
  40. ## The web pages
  41. The same port serves a browser interface for people, in a three-column layout
  42. (navigation rail, timeline, search and tips):
  43. - **Themes.** X (default), Vercel, Mono, Claude, Codex and TikTok, each with a
  44. light and a dark palette. *Light / Dark / System* is in the Appearance menu.
  45. - **Chinese interface.** One click switches the interface to 简体中文. Posts
  46. and names from X are never translated.
  47. - **Optional extras** (on by default, plain pages work without them): a photo
  48. viewer, keyboard shortcuts (`?` lists them) and a word cloud of the searches
  49. made in your own browser. They never leave the browser.
  50. - **No JavaScript needed, no ads, RSS feeds** for profiles, lists and searches.
  51. Details are in [docs/web-ui.md](docs/web-ui.md).
  52. ## Quick start
  53. ```sh
  54. git clone https://github.com/xiaoY233/nitter.git && cd nitter
  55. docker build -t vuldocker/nitter:latest .
  56. # or use the image published by CI: docker pull ghcr.io/xiaoy233/nitter:latest
  57. cp nitter.example.conf nitter.conf # set [Api] enabled = true, redisHost = "nitter-redis"
  58. cp /path/to/sessions.jsonl . # X account sessions
  59. echo "NITTER_API_TOKENS=me:$(openssl rand -hex 24)" > .env
  60. # uncomment the `environment` block in compose.yml, then:
  61. docker compose up -d
  62. ```
  63. Check it:
  64. ```sh
  65. curl http://127.0.0.1:8080/api/v1/health
  66. curl -H "Authorization: Bearer <secret>" \
  67. "http://127.0.0.1:8080/api/v1/users/jack?format=markdown"
  68. ```
  69. `<secret>` is the part of the token after the colon. Open
  70. `http://127.0.0.1:8080` in a browser for the web pages. The full walk-through,
  71. including building from source and systemd, is in
  72. [docs/deployment.md](docs/deployment.md).
  73. ## Connect an agent
  74. MCP, for example with Claude Code:
  75. ```sh
  76. claude mcp add --transport http nitter http://<host>:8080/mcp \
  77. --header "Authorization: Bearer <secret>"
  78. ```
  79. Clients that only speak stdio use the bridge in
  80. [`clients/mcp-stdio`](clients/mcp-stdio). Skills that teach an agent how to
  81. research with these tools are in [`skills/`](skills/README.md). Other clients
  82. and the REST API are covered in [docs/agent-api.md](docs/agent-api.md).
  83. ## Documentation
  84. | Document | Contents |
  85. |---|---|
  86. | [docs/deployment.md](docs/deployment.md) | Docker Compose, `docker run`, source build, systemd, troubleshooting |
  87. | [docs/configuration.md](docs/configuration.md) | Every `nitter.conf` option and the environment variables |
  88. | [docs/sessions.md](docs/sessions.md) | Account sessions, upstream and server rate limits, error meanings |
  89. | [docs/agent-api.md](docs/agent-api.md) | Tools, REST, MCP, data notes, Skills |
  90. | [docs/web-ui.md](docs/web-ui.md) | The X theme and the colour themes, keyboard shortcuts, the Chinese interface |
  91. | [docs/ui-system.md](docs/ui-system.md) | Design tokens and components, for people changing the web pages |
  92. | [skills/README.md](skills/README.md) | Installing the agent Skills |
  93. | [CHANGELOG.md](CHANGELOG.md) | What changed in each release |
  94. ## Notes
  95. - Intended for a trusted network. Every call spends your X session quota, and
  96. X may restrict the account behind a session.
  97. - The API reports unknown numbers (for example views on old tweets) as `null`,
  98. not `0`. See "Data notes" in [docs/agent-api.md](docs/agent-api.md).
  99. ## License and origin
  100. This project is a fork of [zedeus/nitter](https://github.com/zedeus/nitter),
  101. licensed under the [GNU AGPL v3](LICENSE). The agent API, MCP server, Skills,
  102. themes and related changes are by the maintainers of this repository and are
  103. released under the same license. If you offer this software over a network, the
  104. AGPL requires you to make the source of your running version available to its
  105. users. Theme colours come from [tweakcn](https://tweakcn.com) (Apache-2.0); the
  106. agent logos on the home page come from LobeHub (MIT).

Ratings and comments

Sign in to rate this skill.

Sign in

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