Fetch public X posts and threads, and manage text splitting according to X's character limits.
Also known as steley/twittertools, twittertools-mcp
- Stars
- 1
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 1.2.2
- Last commit
- Oct 11, 2026
- License
- MIT
What is TwitterTools MCP?
TwitterTools fetches public X posts and threads, and manage text splitting according to X's character limits. It exposes 5 tools, such as get_tweet, get_thread, count_chars.
Summary generated from the project's README
About TwitterTools MCP server
TwitterTools MCP provides AI agents with the ability to interact with public X content without requiring user logins, tracking, or API keys. It connects to the twittertools.com API to retrieve public posts and threads through X's free syndication endpoint. This server works via stdio and can be integrated into clients like Claude Desktop, Cursor, or Claude Code using npx.
The toolkit includes specific functions for data retrieval and text management. Users can employ get_tweet to fetch post text and media URLs, or get_thread to unroll entire conversations into ordered posts. For content creation, the server offers count_chars to measure text against specific X limits, including CJK character weighting and link lengths, and split_thread to break long text into numbered posts. While data fetching requires a remote API, the text processing tools run entirely offline.
What you can do with it
- 1Retrieve specific post detailsFetch the text, author, and direct media URLs for a specific tweet using its ID or URL.
- 2Unroll social media threadsConvert a long thread of posts into a sequential list of individual messages.
- 3Validate character countsCheck if a piece of text fits within the 280-character limit while accounting for CJK characters and links.
- 4Prepare long content for postingDivide a long piece of writing into multiple numbered posts that fit within platform constraints.
Written from the project's README. Every use case is checked against a quote from it.
How to install TwitterTools MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall TwitterTools MCP in Claude Code
$ claude mcp add twittertools-mcp -- npx -y twittertools-mcpInstall TwitterTools MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"twittertools-mcp": {
"command": "npx",
"args": [
"-y",
"twittertools-mcp"
]
}
}
}Install TwitterTools MCP in VS Code
.vscode/mcp.json
{
"servers": {
"twittertools-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"twittertools-mcp"
]
}
}
}Install TwitterTools MCP in VS Code CLI
$ code --add-mcp '{"name":"twittertools-mcp","type":"stdio","command":"npx","args":["-y","twittertools-mcp"]}'Install TwitterTools MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"twittertools-mcp": {
"command": "npx",
"args": [
"-y",
"twittertools-mcp"
]
}
}
}Install TwitterTools MCP in Codex
$ codex mcp add twittertools-mcp -- npx -y twittertools-mcpInstall TwitterTools MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.twittertools-mcp] command = "npx" args = ["-y", "twittertools-mcp"]
Install TwitterTools MCP in Gemini CLI
$ gemini mcp add -s user twittertools-mcp npx -- -y twittertools-mcpInstall TwitterTools MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"twittertools-mcp": {
"command": "npx",
"args": [
"-y",
"twittertools-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for twittertools-mcp 1.2.2 in an isolated container with no network and no keys. It answered and listed 5 tools.
TwitterTools MCP tools 5
Read from the server with tools/listget_tweetFetch one public X (Twitter) post by URL or ID: text, author, engagement counts, and media with direct CDN URLs (photos, or MP4 video variants sorted by quality). Use for a specific post the user links or cites — not for searching X, timelines, bookmarks, or DMs. Deleted, protected, or age-restricted posts are not available without an X login.
get_threadUnroll a public X thread into its posts in order. For a single post, use get_tweet instead. Expensive upstream — call sparingly, and prefer pasting the thread's LAST post, which returns the whole chain. Results may be partial; the response says so when they are.
count_charsCount text against X's real 280-character limit: CJK and emoji weigh 2, any link weighs exactly 23. Same engine as twittertools.com/tweet-character-counter/.
split_threadSplit long text into numbered posts (1/, 2/, …) that each fit X's 280 weighted-character limit, preferring sentence boundaries and never breaking a URL. Same engine as twittertools.com/tweet-splitter/.
parse_tweet_urlParse a post URL, bare ID, or free text containing an ID: returns the numeric ID, author handle, posting timestamp (decoded from the Snowflake ID), and canonical permalink. Offline.
Configuration
TWITTERTOOLS_API_BASEAPI base of a self-hosted twittertools instance (default: https://twittertools.com)
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesteley/twittertools is public and reachablegithub.com/steley/twittertools ↗Pass
- Package names this repository as its sourcetwittertools-mcp names steley/twittertools as sourcenpmjs.com/package/twittertools-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for twittertools-mcpnpmjs.com/package/twittertools-mcp/v/1.2.2#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-11github.com/steley/twittertools ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from twittertools-mcpPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubtwittertools-mcp
Model Context Protocol server for
TwitterTools — brings the toolkit to AI agents
(Claude, ChatGPT, Cursor, ZCode, …). No login, no tracking, no API keys.
Listed in the official MCP Registry as io.github.steley/twittertools-mcp.
Tools
| Tool | What it does |
|---|---|
get_tweet |
Fetch a public post by URL or ID: text, author, media with direct CDN URLs |
get_thread |
Unroll a thread into its posts, in order (partial results are flagged) |
count_chars |
Measure text against X's real 280-character limit (CJK ×2, links = 23) |
split_thread |
Split long text into numbered, limit-fitting posts |
parse_tweet_url |
URL/ID → ID, author handle, posting time, canonical permalink |
get_tweet / get_thread call the stateless twittertools.com
API, which resolves public posts through X's free syndication endpoint. The other
three run entirely offline. Media is not proxied: tweet results carry the
direct pbs.twimg.com / video.twimg.com URLs, which any client can fetch on its own.
The package has zero dependencies: the MCP protocol layer is hand-rolled (line-delimited JSON-RPC over stdio), so the entire supply-chain surface is the couple hundred lines in this directory — verifiable against Socket or any scanner.
Install
# Claude Code
claude mcp add twittertools -- npx -y twittertools-mcp
Or add it to any client that reads an mcpServers config
(Claude Desktop's claude_desktop_config.json, Cursor's .cursor/mcp.json, …):
{
"mcpServers": {
"twittertools": {
"command": "npx",
"args": ["-y", "twittertools-mcp"]
}
}
}
Requires Node 18+.
Tip:
npxresolves the latest version from the registry on every launch (instant once cached, a few seconds the very first time). For zero startup delay,npm i -g twittertools-mcponce and set"command": "twittertools-mcp".
Self-hosting
Point TWITTERTOOLS_API_BASE at your own instance of
server/downloader_server.py to keep lookups entirely on your
infrastructure:
{ "command": "npx", "args": ["-y", "twittertools-mcp"], "env": { "TWITTERTOOLS_API_BASE": "https://your-instance.example" } }
Privacy
The server is stateless: nothing is stored, no telemetry, no accounts. It talks only to the configured API base. The API itself is rate-limited per IP and keeps only aggregate, anonymous counters — see twittertools.com/privacy.
Development
npm install
cd .. && npx vitest run mcp # unit + stdio protocol tests (offline, mock API)
MIT — same as the main project.
TwitterTools MCP questions
How do I add TwitterTools MCP to Claude Code?
Run claude mcp add twittertools-mcp -- npx -y twittertools-mcp in your terminal. Add --scope user to make it available in every project.
How do I add TwitterTools MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does TwitterTools MCP provide?
It exposes 5 tools, including get_tweet, get_thread, count_chars, split_thread, parse_tweet_url.
Do I need an API key or login to use this?
No, the server requires no login, no tracking, and no API keys.
How does the character counting work?
It measures text against X's real 280-character limit, accounting for CJK characters being double-weighted and links counting as 23 characters.