Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@X Research MCP Find public posts discussing MCP and show ten at a time"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
한국어 · Design and API contract · Verification
A read-only, self-hosted MCP server for public X research. Eight task-oriented tools provide posts, threads, replies, profiles, search, relationships, public collections, trends, and analysis of saved results. It uses the free FxTwitter API first and an optional owner-supplied X session through twscrape where needed. There are no paid API calls or server-side LLM calls.
0.1.0 status: source installation is supported; this is not a claim of PyPI publication. Public post/profile/timeline/thread/reply/trend probes succeeded on 2026-09-16. Free post search returned ambiguous 404s and is reported as unavailable; free user suggestions succeeded through the typeahead route. The session adapter is covered with synthetic tests but has not been tested against an owner's live account. Collections require an explicit public-visibility signal and fail closed when the provider does not supply it. See the capability table before relying on a particular view.
Requires Python 3.12+ and uv.
git clone https://github.com/BK927/x-mcp.git
cd x-mcp
uv sync --frozen --no-dev
uv run --frozen --no-dev x-mcp serveNo X login is needed for the public API. Generic local MCP configuration:
{
"mcpServers": {
"x-research": {
"command": "uv",
"args": ["run", "--frozen", "--no-dev", "--directory", "/absolute/path/x-mcp", "x-mcp", "serve"]
}
}
}Use an absolute Windows path such as C:/Users/you/repo/x-mcp when applicable.
The executable is x-mcp; the distribution is bk927-x-mcp. The generic PyPI
name x-mcp is not this project. Repository main can change; check out a reviewed
commit for reproducible source installations.
Related MCP server: x-mcp-server
Tool | Views / use |
| Public posts or users; posts: latest/top/media |
| post, author thread, replies, quotes, reposters |
| profile, posts, posts with replies, media, articles, followers, following |
| Public list posts/members; community info/posts/members, subject to visibility proof |
| trending; session also supports news/sport/entertainment |
| Saved-post activity, engagement, link domains, hashtags; sample statistics |
| Saved items and lossless text/JSON chunks, without network |
| capabilities, recorded health, or one tool's schema |
Examples: “Read this X thread and cite its posts”; “Find public posts discussing MCP and show ten at a time”; “Compare reaction counts in these saved results, keeping missing metrics separate from zero.”
All tools are read-only. No posting, likes, following changes, DMs, bookmarks, personal home feeds, notifications, account management, or protected content. Search and replies are samples, not a complete X archive. Trend geography is provider-controlled and is not inferred from the client's language.
Install the session extra, and keep --extra session in the MCP launch command:
uv sync --frozen --no-dev --extra session
uv run --frozen --no-dev --extra session x-mcp auth import --file /private/path/export.json
uv run --frozen --no-dev --extra session x-mcp serveImport accepts a JSON cookie list, Playwright storage-state JSON, a dictionary
containing auth_token and ct0, or a Netscape cookie file. Only those two X
cookies are retained. Do not paste them into a chat or tool argument.
Alternatively, log in manually in a fresh dedicated browser:
uv sync --frozen --no-dev --extra session --extra browser
uv run --frozen --no-dev --extra session --extra browser playwright install chromium
uv run --frozen --no-dev --extra session --extra browser x-mcp auth loginFinish authentication in the window, then press Enter in the terminal. This does
not import an everyday browser profile, automate passwords, or bypass challenges.
The browser closes after saving the same session file used by auth import.
It is not needed while the server runs. A headless server can mount a session
file prepared on a trusted local machine.
x-mcp auth status validates file presence/format only. x-mcp doctor reports
sanitized configuration and recorded health. x-mcp doctor --live explicitly
queries one public post, profile, and search, using the configured routes.
Session expiry requires reconnecting the account; there is no account rotation.
Lists default to ten items, at most fifty. detail=compact preserves post ID,
URL, author, timestamp, text and basic reaction counts. Long text is excerpted at
600 characters with a marker. full requests extra fields but still obeys the
12 KiB normalized-payload cap. Both MCP text and structured representations are
provided for compatibility, so clients may consume approximately twice the
payload's tokens; benchmarks report that representation too.
Use a query response's page.next_cursor with the original tool and unchanged
selection arguments. Output-limited leftovers are served before another source
page is fetched. Provider cursors are never mixed. Stored results last one hour
and survive restarts in the same state directory.
For full text: x_result_get(result_id=..., item_id=...). Continue with its
page.next_cursor. Use field=json for lossless chunks of the entire normalized
item. For saved item pages, x_result_get never fetches upstream; its
page.source_cursor, when present, must be passed to the original query tool.
x_analyze processes only posts already saved, not unvisited source pages.
The fixed EN/KO/JA list benchmark meets the 6,000-token tool-list and 50% median payload-reduction targets. Actual savings depend on workload and client; see the methodology and results.
uv run --frozen --no-dev --extra session x-mcp serve --transport httpEndpoints: http://127.0.0.1:8766/mcp, http://127.0.0.1:8766/healthz.
Set MCP_ACCESS_TOKEN to a random secret of at least 32 characters before binding
outside loopback. For HTTPS ingress set PUBLIC_BASE_URL=https://x-mcp.example.com
to your exact origin. Clients send Authorization: Bearer ....
Docker is a single-user, single-instance deployment with a persistent state volume. See deployment instructions. Web ChatGPT-specific OAuth, multi-user SaaS, Cloud Run and background collectors are outside v0.1.
Environment variable | Default |
| OS user-data directory |
|
|
| 12288; configurable 4096–32768 |
| 3600 seconds; configurable 60–86400 |
| 127.0.0.1, 8766 |
| Empty; mandatory for non-loopback HTTP |
| Empty; exact HTTPS origin for remote host/origin validation |
State contains public-result snapshots, cached queries, a cursor signing key, health observations and optional session/account files. Queries may themselves be sensitive. Files stay on your machine; protect the whole state directory. FxTwitter receives public lookup IDs/handles/searches, never X cookies. twscrape telemetry is disabled. See privacy and security.
uv sync --frozen --extra session --extra browser
uv run --frozen --extra session --extra browser ruff check src tests scripts
uv run --frozen --extra session --extra browser pytest -q
uv run --frozen --extra session --extra browser python scripts/benchmark_tokens.pyscripts/live_smoke.py makes explicitly opted-in public network calls and stores
only local artifacts. CI uses fixtures, MCP process/HTTP checks and a Docker
smoke test. Browser login and live account access remain operator-run checks.
MIT. Unofficial and unaffiliated with X Corp. Free means no paid data API is called; provider availability, access terms and future pricing can change.
Aggregate saved public post results: activity, engagement, link domains, hashtags. No new network fetches or LLM inference; sample statistics only.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | summary | |
| result_ids | Yes |
| Name | Required | Description |
|---|---|---|
| data | No | |
| meta | No | |
| page | No | |
| error | No | |
| items | No | |
| result_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond that, explicitly stating 'No new network fetches or LLM inference; sample statistics only,' which tells the agent the tool is purely computational over saved data. This enriches the annotation information without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one focused, front-loaded sentence. The core action and resource come first, followed by the most important behavioral constraints. There is no filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema and annotations covering read-only, idempotent, non-destructive behavior, the description supplies the remaining needed context: what is aggregated, the categories, and the no-network/no-inference constraint. It is complete enough for an agent to select and call the tool correctly, though it could be slightly stronger with explicit mode-by-mode semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It partially does: 'saved public post results' clarifies what result_ids refer to, and the list 'activity, engagement, link domains, hashtags' maps directly to the mode enum values. However, it does not explain the maxItems constraint, the default mode, or what each specific mode returns, leaving the agent to infer those from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Aggregate saved public post results,' followed by the exact aggregation dimensions. The clause 'No new network fetches or LLM inference' further distinguishes it from sibling tools like x_search, which retrieve live data. This is unambiguous and easily separable from the other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly scopes when the tool is appropriate: it operates only on already-saved public post results and performs no new network fetches or LLM inference. This is a useful exclusion that prevents an agent from choosing it for live search tasks, though it does not explicitly name alternatives or state conditions like 'use x_search when you need fresh posts.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read public list/community posts or members; community info is also supported. Requires a session and explicit public visibility proof.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| view | No | posts | |
| limit | No | ||
| cursor | No | ||
| detail | No | compact | |
| collection | Yes |
| Name | Required | Description |
|---|---|---|
| data | No | |
| meta | No | |
| page | No | |
| error | No | |
| items | No | |
| result_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add extra context. It adds value by disclosing session and public-visibility-proof requirements, which are not visible in the annotations or schema. There is no contradiction with the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, and the primary read scope is front-loaded before the follow-up requirement. Every clause adds useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given strong read-only/idempotent annotations and an output schema, the description covers the main call intent and the key precondition. Some gaps remain around what 'collection' refers to and how pagination works, but these are minor for a tool whose schema already exposes limit, cursor, and enum defaults.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description does some compensation by connecting 'list/community' to kind and 'posts/members/info' to view. But it does not explain collection, limit, cursor, or detail semantics, leaving several parameters under-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and a clear resource ('public list/community posts or members') plus the additional supported 'community info' view. It also maps cleanly onto kind/view values in the schema, though it does not explicitly differentiate itself from sibling tools like x_post_get or x_user_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives useful context by stating that a session and explicit public visibility proof are required, which tells the agent when the tool is usable. However, it does not provide when/when-not guidance or name any alternatives, leaving routing decisions to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a public post by ID/URL, its author thread, replies, quotes, or reposters. Long text can be recovered from its result_id.
| Name | Required | Description | Default |
|---|---|---|---|
| post | Yes | ||
| sort | No | latest | |
| view | No | post | |
| limit | No | ||
| cursor | No | ||
| detail | No | compact |
| Name | Required | Description |
|---|---|---|
| data | No | |
| meta | No | |
| page | No | |
| error | No | |
| items | No | |
| result_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by noting that long text can be recovered from result_id and by listing the supported views (thread, replies, quotes, reposters), which are behavioral details not present in annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundancy. The first sentence front-loads the core functionality, and the second adds a useful recovery detail. It is well-structured and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema and 6 parameters, but the description covers only the primary use case. It omits explanations for parameters like sort, limit, cursor, and detail, and does not mention pagination behavior. While the output schema helps define return values, the description is adequate but not fully complete for an agent to understand all calling options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for missing parameter documentation. It clarifies that 'post' accepts an ID or URL and hints at the 'view' parameter by listing thread/replies/quotes/reposters. However, it does not explain 'sort', 'limit', 'cursor', or 'detail' parameters, leaving them opaque. The description only partially compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Read' and a clear resource 'public post', and enumerates the available views (thread, replies, quotes, reposters). It distinguishes this tool from siblings like x_search and x_user_get by focusing on retrieving a post by ID/URL. No tautology; it clearly conveys the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you have a post ID or URL and need to fetch the post or related content, which gives some context. However, it does not explicitly state when to avoid this tool or mention alternatives (e.g., 'use x_search to find posts first'). Thus usage is implied but not explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read saved results without network. Set item_id for full text chunks, or field=json for lossless object chunks. source_cursor resumes the original query tool.
| Name | Required | Description | Default |
|---|---|---|---|
| field | No | text | |
| limit | No | ||
| cursor | No | ||
| detail | No | compact | |
| item_id | No | ||
| result_id | Yes |
| Name | Required | Description |
|---|---|---|
| data | No | |
| meta | No | |
| page | No | |
| error | No | |
| items | No | |
| result_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral context: no network access, chunk-type semantics, and the ability to resume the original query via a cursor. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately short and front-loaded with the core purpose. Each sentence adds information, though the second sentence is somewhat dense and the 'source_cursor' reference creates avoidable ambiguity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The annotations and output schema cover a lot, and a basic call is understandable. However, the description omits how result_id is obtained and leaves the cursor/pagination behavior confusing because 'source_cursor' does not match the schema parameter name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must carry parameter meaning, but it only explains field and item_id, and references 'source_cursor' while the actual schema parameter is 'cursor'. Limit and detail are left unexplained, and the source of the required result_id is not clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action and object: 'Read saved results without network.' The phrase 'saved results' distinguishes it from live-query siblings like x_search, though it does not explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool ('without network', 'saved results') and provides conditional guidance for item_id vs field=json. It does not explicitly state when not to use it or name sibling alternatives, but the workflow implication is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search public X posts or users. Prefer small pages; results are not exhaustive. Continue with identical query and cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | latest | |
| limit | No | ||
| query | Yes | ||
| scope | No | posts | |
| cursor | No | ||
| detail | No | compact |
| Name | Required | Description |
|---|---|---|
| data | No | |
| meta | No | |
| page | No | |
| error | No | |
| items | No | |
| result_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark read-only and idempotent, and the description adds meaningful behavior beyond that: results are not exhaustive (open-world), small pages are preferred (cost/latency hint), and pagination requires keeping the query identical while advancing the cursor. This is highly actionable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sentences. The core action is front-loaded, and every sentence adds value: what it searches, how to paginate, and the non-exhaustive caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and strong annotations, the description need not restate return values or safety. It covers the essential behavioral context for calling the tool correctly. A brief mention of when to prefer a sibling tool would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the query and cursor relationship, the posts-or-users scope, and implies a small page size via 'prefer small pages.' It does not explain sort or detail, but those are self-explanatory enums, so the key parameter behaviors are covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') with a clear resource ('public X posts or users') and scope ('public'). This distinguishes it from sibling get/analyze/trends tools without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear operational guidance: prefer small pages, expect non-exhaustive results, and continue with the identical query and cursor. It does not explicitly name alternative tools or when-not-to-use conditions, but the context is sufficient for correct use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect capabilities/configuration or recorded provider health. view=schema with tool=NAME returns that tool's input rules. Does not make live probes.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | ||
| view | No | capabilities |
| Name | Required | Description |
|---|---|---|
| data | No | |
| meta | No | |
| page | No | |
| error | No | |
| items | No | |
| result_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds valuable behavioral context by stating 'Does not make live probes' and clarifying that health is 'recorded' rather than actively checked. This prevents an agent from expecting network probing or real-time health checks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no filler. It front-loads the core purpose, then adds the schema-mode detail positionally tight to the parameter pair, ending with a crucial caveat about live probes. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter introspection tool with an output schema and read-only annotations, the description covers the essential behavior, the non-live nature, and the schema view mode. The main remaining gap is a precise specification of what tool=null does outside schema view, though the schema defaults and enums partially mitigate this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry parameter meaning. It does clarify the view=schema behavior and the role of tool=NAME, and the schema's enums add value for the remaining options. However, it does not explain the default behavior for tool=null or the exact meaning of each view value beyond the schema view.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Inspect') and resource ('capabilities/configuration or recorded provider health'), and it distinguishes the tool from the operation-focused siblings by defining it as a meta/introspection tool. The view=schema mode is explicitly tied to returning another tool's input rules, making its role unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to inspect capabilities, configuration, provider health, or another tool's input schema. It does not explicitly name alternatives, but none of the siblings serve this introspection purpose, so the implied usage is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read provider-context trends. Geography is unknown unless supplied by the source; news/sport/entertainment require a session.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| detail | No | compact | |
| category | No | trending |
| Name | Required | Description |
|---|---|---|
| data | No | |
| meta | No | |
| page | No | |
| error | No | |
| items | No | |
| result_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context beyond annotations: geography is unknown unless supplied, and certain categories (news/sport/entertainment) require a session. This discloses operational constraints that an agent needs to know before invoking the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, two sentences, and front-loads the primary purpose. The second sentence is slightly dense but conveys key constraints efficiently. No filler words; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 0% schema coverage and no output schema explanation (though output schema exists, it doesn't cover parameters), the description is incomplete. It fails to explain pagination (cursor), result size (limit), and detail level. The 'provider-context' phrase is undefined. An agent would need to probe or guess for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. It only partially addresses the 'category' parameter by noting that news/sport/entertainment require a session, but it does not explain limit, cursor, or detail. This leaves most parameters undefined, forcing the agent to infer their meaning from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Read provider-context trends.' It is distinct from siblings like x_post_get or x_user_get, and the phrase 'provider-context' adds specificity. However, it does not explicitly contrast with x_search, which could also return trending content, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over siblings. It does not mention alternatives or conditions like 'use this when you need trends' or 'use x_search for general queries.' The only contextual hints are the geography and session caveats, which do not address tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a public profile or a page of posts, posts with replies, media, articles, followers, or following. Accepts @handle/profile URL.
| Name | Required | Description | Default |
|---|---|---|---|
| user | Yes | ||
| view | No | profile | |
| limit | No | ||
| cursor | No | ||
| detail | No | compact |
| Name | Required | Description |
|---|---|---|
| data | No | |
| meta | No | |
| page | No | |
| error | No | |
| items | No | |
| result_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the 'public' scope and input format, but does not disclose pagination behavior, rate limits, or how errors are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The action is front-loaded ('Read...'), and the input format note is directly useful. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is compact but covers the core operation, the supported resource types, and the input format. An output schema exists, so return value details are not required here. It could improve by explaining cursor pagination, but the essentials for a correct call are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needs to compensate. It adds value by explaining the 'user' parameter as accepting '@handle/profile URL' and paraphrases the view enum. However, limit, cursor, and detail parameters receive no explanation beyond what the schema already shows.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Read a public profile or a page of posts...' and enumerates the views, making the tool's function apparent. It does not explicitly distinguish itself from sibling tools like x_post_get or x_collection_get, but the user-focused scope implies differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when reading public user data such as profile, posts, replies, media, articles, followers, or following. However, it does not provide explicit when-not-to-use guidance or mention any alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0x_analyzex_collection_getx_post_getx_result_getx_searchx_statusx_trends_getx_user_getScored across 8 tools
Each tool targets a clearly distinct data surface: search, post, user, collection, trends, saved-result analysis, raw saved-result retrieval, and server status. x_analyze and x_result_get both operate on saved results, but one computes aggregates while the other returns raw stored chunks, so an agent should not confuse them.
Most tools follow an x_<resource>_get pattern: x_post_get, x_user_get, x_collection_get, x_trends_get, and x_result_get. The exceptions are x_search, x_analyze, and x_status, which break that resource-get convention, but the shared x_ prefix and lowercase snake_case keep the naming mostly predictable.
Eight tools is well-scoped for a read-only X research server. Each tool serves a distinct need, and none feel redundant or excessive for the stated purpose.
The tool surface covers search, post/user/collection/trends reads, saved-result access, and aggregation, which supports the research workflow well. Minor gaps such as no explicit saved-result listing/deletion or batch operations can be worked around by repeated calls or using existing saved-result access.
X / Twitter public post, comment, reply, user, and search tools.
Twitter/X read-only MCP server — 12 tools: search, users, tweets, followers, timelines, trends.
X (formerly Twitter): X (formerly Twitter) public and private data API for search, posts (Tweets).
Live X/Twitter and Reddit research. 10 read-only MCP tools, Google/GitHub sign-in. Free tier.
