A Twitter MCP server gives an AI assistant a safe way to read X. TwitterViewer runs one as a remote server at https://twitterviewer.app/mcp. Add it to Claude, Claude Code, Cursor or Codex, and the assistant can turn an X link into Markdown, read the replies under a post, search public posts and check what is trending, without you copying and pasting anything.
The server is read-only. It cannot post, reply, like, follow, send messages or open private accounts, and it is an independent service with no connection to X Corp. This guide explains what a Twitter MCP server is, how to connect it in each client, how sign-in works, what the five tools do, how credits are charged, and how to solve the common problems.
What is a Twitter MCP server?
MCP, the Model Context Protocol, is an open standard that lets an AI client call tools provided by another program. A Twitter MCP server is a server that offers tools for reading X (Twitter) through that standard. Instead of pasting a thread into a chat, you ask the assistant to read a link, and the assistant calls the tool, gets Markdown back and works with it.
The server here is remote. There is nothing to install and no process to keep running on your machine: your client connects to a URL over Streamable HTTP. It is the same service as the Twitter API, so the same credits are used, one credit per post returned, and a call that fails is free.
You may also see it called an X MCP server or a Twitter MCP. They all mean the same thing: a tool server that lets an agent read public posts. The difference between servers is what they can do. This one only reads public content, on purpose.
What can a Twitter MCP server do for your agent?
Once connected, an agent can do four kinds of work with X content:
- Read a link. Give it the address of a post, a thread or a profile and it returns Markdown, Obsidian notes, plain text or JSON.
- Search. Ask it to find public posts with X search operators, such as everything from an account that got at least 100 likes. Search is part of Pro and Business.
- Read replies. Ask what people are answering under a post and which objections repeat.
- Check trends. List what is trending in a region.
Because the answers arrive as Markdown, they are cheap to put in a model's context and keep the structure of the original: the order of posts in a thread, the links the author shared, the image references. The agent does not scrape a web page and guess; it gets a document.
Connect the Twitter MCP server
The server URL is https://twitterviewer.app/mcp. Pick your client below. Each snippet connects with browser sign-in, which is the simplest way.
Claude Code
Run one command in your terminal:
claude mcp add --transport http twitterviewer https://twitterviewer.app/mcp
Start Claude Code, run /mcp to see the server and follow the sign-in link the first time. After that, ask in plain language: "Read https://x.com/username/status/1234567890123456789 as Markdown."
Claude
In Claude on the web or the desktop app, open Settings, go to Connectors, choose Add custom connector and paste the server URL. Claude opens a browser window so you can sign in to TwitterViewer. The tools then appear in your chats.
Cursor
Add the server to your mcp.json:
{
"mcpServers": {
"twitterviewer": { "url": "https://twitterviewer.app/mcp" }
}
}
Open Cursor's MCP settings, enable the server and sign in when it asks.
Codex
Add the server to your Codex configuration file:
[mcp_servers.twitterviewer]
url = "https://twitterviewer.app/mcp"
Restart Codex and it will list the five tools.
Sign in with your browser or an API key
There are two ways to authorise the Twitter MCP server, and you can choose per client.
Browser sign-in is the default. The first time a client connects, it opens your browser so you can sign in to TwitterViewer and approve the connection. Nothing else needs configuring, and you never copy a secret.
An API key is for places without a browser: servers, CI jobs and some editors. Create a key on the API page, export it as TWITTERVIEWER_API_KEY and send it as a Bearer token. In Claude Code add --header "Authorization: Bearer $TWITTERVIEWER_API_KEY" to the command. In Cursor add a headers entry with the same value. In Codex add bearer_token_env_var = "TWITTERVIEWER_API_KEY" below the URL.
Either way, calls are billed to the account that signed in. Keep keys out of shared files and repositories, and delete a key on the API page if it leaks. Every account can hold at least one key: 1 on a free account, 2 on Plus, 5 on Pro and 20 on Business.
The five tools
All five are read-only, and they appear to the agent with these names.
| Tool | What it does | Cost |
|---|---|---|
convert_x_url | Turns a post, thread or profile link into Markdown, Obsidian, text or JSON | 1 credit per post |
search_x_posts | Searches public posts with X search operators (Pro and Business) | 1 credit per post |
get_x_replies | Reads the public replies under a post | 1 credit per reply |
get_x_trends | Lists what is trending in a region | 1 credit per call |
get_credits | Shows your balance and where it comes from | Free |
convert_x_url takes the link, a scope (post, thread or conversation), a format and, for profiles, how many posts to return. It is the tool agents use most. search_x_posts takes a query and a maximum number of posts, and it needs a connected X account because X only serves search to signed-in users. The full argument list is in the API docs.
What to ask your agent
A tool server is only useful if you know what to ask. These prompts work well once the server is connected:
- "Read this thread and give me the five key points: https://x.com/username/status/1234567890123456789"
- "Search X for posts about our launch from the last week and group them by theme."
- "What are people replying to this post? Show me the objections that repeat."
- "Convert this thread to Obsidian Markdown and save it as a note."
- "What is trending in Japan right now?"
- "How many TwitterViewer credits do I have left?"
Agents can combine the tools. A research task might search for posts, convert the three most relevant threads, read the replies under one of them and then write a summary. Each step is a separate tool call and each is billed by the posts it returns, so you can see the cost in get_credits afterwards.
If you only need one thread once, the X to Markdown page does the same job in a browser, and the Twitter Thread Reader shows a thread on one page. The MCP server is for agents that should do it themselves.
Workflows that use the Twitter MCP server
Single questions are easy. The server earns its place when an agent chains the tools into a small workflow. Three patterns come up again and again.
Reading list triage. You paste ten X links into a chat and ask which are worth reading. The agent calls convert_x_url on each with scope set to thread and stats turned off to keep the text short, then ranks them by how much each adds. Nine of the ten may be a single post, so the bill is often close to ten credits.
Topic research. You ask the agent to learn what people think about a product. It uses search_x_posts with a few operators, converts the best two or three threads, reads the replies under the most discussed post with get_x_replies, and writes a short report with links back to the sources. The credit cost is the number of posts it actually read, which get_credits shows afterwards.
Notes capture. You ask for a thread as an Obsidian note. The agent calls convert_x_url with the obsidian format, which adds frontmatter with the author, date and source link, and writes the file in your vault. This is the same output as the X to Markdown page, produced without leaving the chat.
Two habits keep these workflows cheap. Ask for a thread rather than a profile unless you really need recent posts, because a profile of 200 posts costs 200 credits. And tell the agent to stop and ask before it converts more than a handful of long threads, so you stay in control of the balance.
Credits and limits
Credits work as they do in the REST API. One credit is one post returned. Author details are free. A failed call, an empty result or a PDF that could not be rendered is not charged. A free account gets 50 credits once, the paid plans add 3,000, 8,000 or 25,000 credits a month, and credit packs of 1,000, 6,000 and 20,000 credits cost $5, $20 and $50 and never expire. See the pricing page for plans.
Calls are limited per account per minute: 10 on a free account, 30 on Plus, 60 on Pro and 300 on Business. If your agent runs a loop, the limit protects the balance too. When credits run out, a tool does not fail with a stack trace: it answers with one line and a link to the pricing page, and the agent can pass that on to you.
The data has the same limits as the API. Only public posts are available, so private accounts, protected posts, direct messages, deleted posts and suspended accounts return nothing useful. Content is cached for a short time, around two minutes for a post, so a very fresh edit may not show yet.
Read-only by design
Many people worry about giving an agent access to a social account, and for good reason: an agent with write access can post by mistake. This Twitter MCP server avoids the problem. It has no tool that posts, replies, likes, reposts, follows, blocks or sends a message, and it never asks for your X password or tokens. The worst a confused agent can do is spend credits on reading, and the rate limit and your balance cap that.
Search is the one feature that touches an X account, because X shows search results only to signed-in users. It uses the X account you connect yourself on a Pro or Business plan, only for requests you or your agent make, and you can disconnect it at any time.
Twitter MCP server, API, CLI or domain swap: which to use?
The four ways in share one balance, so pick by where the work happens.
- MCP server: best when an assistant such as Claude, Cursor or Codex should decide when to read X. No code and no copy-paste.
- REST API: best for scripts, pipelines and apps you write. See the Twitter API page.
- Command-line tool:
npx twitterviewer <link>for a quick conversion in a terminal or a shell script. - Domain swap: replace
x.comwithtwitterviewer.appin a link and send your key; the response is Markdown.
An Agent Skill at /.well-known/agent-skills/twitterviewer/SKILL.md can teach an agent to choose between them when it meets an X link.
Troubleshooting the Twitter MCP server
If the server does not connect, check these first.
- The client says it cannot reach the server. Confirm the URL is exactly
https://twitterviewer.app/mcp. Clients that only support local servers need a bridge; Claude Code, Claude, Cursor and Codex connect to remote servers directly. - The browser sign-in loops. Finish the sign-in in the same browser profile the client opened, and make sure you are signed in to the account you want to bill.
- A tool answers that credits ran out. Check
get_credits, then buy a pack on the pricing page or wait for the monthly pool to reset. - Search is refused. Search needs Pro or Business and a connected X account. Connect it on the X account page of your settings.
- A link returns nothing. The post may be deleted or protected, or the account suspended. Open the link in the profile viewer to see what is public.
- You see a rate-limit message. Wait the number of seconds it gives, or move to a plan with a higher per-minute limit.
Twitter MCP server FAQs
What is a Twitter MCP server?
A Twitter MCP server is a server that lets an AI assistant read X through the Model Context Protocol. TwitterViewer's version is remote, read-only and returns Markdown, so an agent can read a thread, search posts, read replies and check trends from inside Claude, Cursor or Codex.
Is this an official X MCP server?
No. It is an independent service and is not affiliated with X Corp. It reads public posts only and cannot post, like, follow or send messages.
How do I add the Twitter MCP server to Claude Code?
Run claude mcp add --transport http twitterviewer https://twitterviewer.app/mcp, then open /mcp inside Claude Code and sign in with your browser the first time. After that, ask the assistant to read an X link.
Does it work with Cursor and Codex?
Yes. In Cursor add the URL under mcpServers in mcp.json. In Codex add a [mcp_servers.twitterviewer] block with the URL. Both can sign in through the browser or use an API key as a Bearer token.
Do I need an API key?
No. Browser sign-in works without a key. A key helps in places without a browser, such as servers and CI, and you can create one on the API page.
What can the tools do?
There are five: convert_x_url, search_x_posts, get_x_replies, get_x_trends and get_credits. All are read-only. They convert links, search public posts, read replies, list trends and show your balance.
How much does it cost to use?
It uses the same credits as the API: one credit per post returned, with author details and failed calls free. A free account gets 50 credits once, and plans add 3,000, 8,000 or 25,000 credits a month. Credit packs cost $5, $20 and $50 and never expire.
Can the agent post or like for me?
No. The server has no tool that writes to X. It cannot post, reply, like, repost, follow or send messages, and it never asks for your X password.
Why does search need Pro or Business?
X shows search results only to signed-in users, so search needs an X account. It is part of Pro and Business and uses the account you connect yourself.
Can I use the Twitter MCP server for private accounts?
No. Only public content is available. Private accounts, protected posts, direct messages and deleted posts are not returned.