A
licenseNot graded
qualityD
maintenanceSearch X (formerly Twitter) in real-time from your AI assistant using xAI's Grok API, with no X API account required.
19 npm
MIT
agent-x-search
Summary: This server gives an agent native X/Twitter search via Grok, returning cited original posts with transparent usage.
Run
x_searchto search X/Twitter through one Grok Responses request with original-post citations.Provide a required
query(1–6000 chars) as the search term.Control result count with
count(1–20, default 5; guidance only).Filter by users with
include_handlesorexclude_handles(mutually exclusive, up to 20 handles each).Restrict results by date range using inclusive
from_dateandto_date(YYYY-MM-DD).Choose media type with
media(none,images,videos,both).Set response depth with
detail(brief,standard,detailed).Receive structured results including
answer, citations, citation status, backend, model, and elapsed time; no automatic retries occur.Use either subscription OAuth or paid xAI API-key mode depending on configuration.
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., "@agent-x-searchSearch X for recent posts about AI agents and include original post URLs."
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.
Agent X Search
Give your agent native X search, with original-post citations and transparent usage.
中文 · Client setup · Recorded walkthrough · Measured overhead
An unofficial, local stdio MCP server. Existing Grok subscription login by default; explicitly selected xAI API keys are also supported. No browser automation, HTTP server, background service, build step or runtime dependencies.
Version 0.1.1 — GitHub release archive · npm versions. If npm does not yet list 0.1.1, install the GitHub .tgz archive using the fixed-path instructions below. API-key mode is experimental and has not been live-tested. Verification matrix.
A 30-second walkthrough
Ask your agent:
Find one recent official Grok feature announcement on X. Include its date and original post URL.
A recorded subscription CLI run returned:
24 Aug 2026 — Grok Voice Think Fast 2.0 announcement.
Original post: https://x.com/SpaceXAI/status/2091987538999197752
That call took 32.794 seconds, one model round. This is historical output from the local predecessor, not a speed promise or a new run of this candidate. Provenance and transcript replay.
Related MCP server: grok-build-plugin
Connect
Requires Node.js 24.5+, a local MCP client, network access, and an eligible Grok subscription session or xAI API key. Zero runtime dependencies does not mean zero account requirements or free searches.
Quick start:
codex mcp add agent-x-search -- npx -y agent-x-search@0.1.1 serve
claude mcp add --transport stdio agent-x-search -- npx -y agent-x-search@0.1.1 servex_search defaults to 300 seconds; opt-in x_deep_search defaults to 900 seconds. Both limits are editable with --timeout-ms / --deep-timeout-ms (or their environment variables, 1 second to 1 hour). Generate a complete config without changing files:
npx -y agent-x-search@0.1.1 config --client codexOther targets: claude-code, cursor, vscode, opencode, cline. One package, not six plugins. Client setup and verification levels.
Fixed-path installation
Avoid runtime npx lookups by installing into a directory you choose:
npm install --prefix /absolute/path/to/agent-tools --omit=dev --ignore-scripts agent-x-search@0.1.1
node --use-env-proxy /absolute/path/to/agent-tools/node_modules/agent-x-search/bin/agent-x-search.mjs config --client codex --localOn Windows, use your own absolute path and quote paths containing spaces. Paste the generated config into your client. It starts the installed file directly; no global npm installation or OS startup item is needed. To install the GitHub archive, use the downloaded agent-x-search-0.1.1.tgz instead of the package name.
From source: node --use-env-proxy bin/agent-x-search.mjs serve. Only contributors running tests need npm ci.
Authentication and billing
Default OAuth: install and sign in with the official Grok CLI, then run grok models to populate its metadata. This package reads that existing session into memory, implements no login, and copies no tokens. If expired, official grok models handles refresh. Ordinary searches do not launch the CLI.
The subscription proxy is an internal compatibility surface, not a guaranteed public third-party API. Eligibility, quota and protocol behavior can change. This project is not affiliated with xAI or X and does not promise unlimited or free access.
Explicit API-key mode: use serve --auth api-key with XAI_API_KEY in the MCP server environment. It calls the official xAI Responses endpoint and incurs API charges; no Grok CLI is required. This path has offline contract coverage, not live validation. Never put a key in a prompt or issue.
There is no automatic billing switch. Setting XAI_API_KEY alone does not change OAuth mode. Failed or uncertain requests are never retried or sent to another backend.
npx -y agent-x-search@0.1.1 doctor
npx -y agent-x-search@0.1.1 doctor --auth api-keyDoctor only reads local state. It does not search, refresh tokens, or validate credentials against xAI.
Tools
Tool | Behavior |
| Default and normally the only tool. One Responses request; xAI may perform several internal searches. |
| Opt in with |
Both default to Grok 4.6; --model MODEL selects another model available to your auth mode without a discovery request. API-key mode rejects --enable-deep to avoid mixing billing modes.
Inputs: query, include_handles or exclude_handles, inclusive from_date/to_date, desired count (1–20), media (none, images, videos, both), and detail (brief, standard, detailed). Count/detail are guidance, not retrieval guarantees. Native parameter contract.
Results retain answer, x_citations, citation_count, citation_status, backend, model, elapsed_ms; add auth_mode, usage, and incomplete. Missing usage is unknown, not zero. Verify claims against original posts. MCP structured content includes a JSON text fallback for compatibility; client handling determines actual context usage.
Configure and troubleshoot
Flags override environment variables, then defaults. No project config file is needed. --help and generated client configs show both timeout controls; generated Codex/OpenCode/Cline configs give the selected server limit another 30 seconds to return. All settings and errors.
reauth_required: use officialgrok modelsorgrok login.cli_metadata_required: rungrok models; version headers come from its cache.cli_unavailable: install official Grok CLI or set--grok-cli; direct API-key search does not need it.unsafe_cli_integrations: deep mode refuses your discovered hooks/plugins/MCP/LSP integrations; direct search is independent of that toolset.rate_limited: wait for quota availability; no retry occurred.request_uncertain: a timeout may already have consumed quota or API spend. Do not assume it was free.Startup/discovery failure: run doctor as the same OS user, check Node/paths, then the client's MCP diagnostics. No model call is needed to diagnose transport.
Connection timeout around ten seconds: your MCP client may not inherit terminal proxy variables. Explicitly configure HTTP_PROXY/HTTPS_PROXY/NO_PROXY in its server environment and reload the connection. Version 0.1.1 adds opt-in proxy config export and
doctor --network; see proxy setup. Upgrade from 0.1.0 to use these flags. Directly connected networks need no proxy configuration.
No telemetry or persistent result cache. Grok may retain its normal CLI session metadata. See engineering evidence, architecture and limits, and contributing. MIT licensed.
Available Tools
1 toolx_searchARead-only
Search X/Twitter with native Grok search. One Responses request, original-post citations, explicit no-source status and reported usage. No automatic retry. Uses the configured subscription or paid API mode.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Desired number; prompt guidance, not an API guarantee. | |
| media | No | none | |
| query | Yes | ||
| detail | No | brief | |
| to_date | No | YYYY-MM-DD, inclusive. | |
| from_date | No | YYYY-MM-DD, inclusive. | |
| exclude_handles | No | ||
| include_handles | No | Mutually exclusive with exclude_handles. |
TDQS
A4.1/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only and non-destructive annotations, the description discloses meaningful behavioral details: it performs a single Responses request, provides original-post citations, explicitly reports no-source status, reports usage, does not automatically retry, and depends on subscription or paid API mode. This is substantial context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose, then packs important behavioral caveats into a few short sentences. There is no filler or redundant restatement of schema fields, and every sentence adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives strong behavioral context such as citations, no-source status, no retry, and API mode, which helps an agent understand side effects and limits. With no output schema, it does not fully describe the return shape, but it does disclose key output-related behaviors. Given the 8-parameter schema and missing parameter documentation for some fields, a bit more parameter context would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, leaving query, media, detail, and exclude_handles without descriptions in the schema. The tool description does not compensate for these gaps; it adds no parameter-level meaning beyond stating the search purpose. The schema covers count and dates, but the description itself adds essentially no parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Search X/Twitter with native Grok search.' It clearly identifies the tool's function and even distinguishes the mechanism (native Grok search) from generic search. There are no sibling tools to differentiate, so this is fully unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching X/Twitter and notes the operational mode ('configured subscription or paid API mode'), but it does not explicitly state when to choose this tool over alternatives, provide exclusions, or describe typical scenarios. With no sibling tools, alternative routing is not required, but explicit usage guidance is still missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v0.1.0- First observed
x_search
TDQS
A4.3/5.0
Scored across 1 tool
Disambiguation5/5
With only one tool, there is no possibility of overlap or confusion between tools. The single x_search tool has a clear, singular purpose: searching X/Twitter.
Naming Consistency5/5
The tool name x_search uses a clear snake_case verb_noun convention that directly reflects its function. With only one tool, there are no conflicting naming patterns to assess.
Tool Count4/5
A single tool is on the thin side, but it is appropriate for a server dedicated exclusively to search functionality. The tool is well-scoped and earns its place.
Completeness5/5
For the stated purpose of searching X/Twitter, the tool provides complete coverage of the domain. There are no obvious missing search-related operations, and the description suggests a robust implementation.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
X (Twitter) data for AI agents: tweets, profiles, followers, search, trends + social listening.
Your agent needs X/Twitter data — who follows a competitor, what a community is posting, who quoted that tweet, what is trending in Japan. Normally that means applying for an X developer account, passing app review, and managing a quota per endpoint. **What you can ask for** • "Who follows @stripe, and which of them are verified?" • "Pull every reply and quote on this tweet and summarise what people object to." • "List this community's moderators and its posts this week." • "What is trending in Japan right now?" • "Give me the full thread context behind this link, including the long-form article." **How to use it** Point any MCP client at https://mcp.aisa.one/twitter-api/mcp and sign in with OAuth — there is no key to create or paste. 29 read tools: users (profile, about, batch lookup by id, search, followers, verified followers, followings, follow check), tweets (timeline, latest, mentions, advanced search, replies, quotes, retweeters, thread context, articles), communities, lists, Spaces and trends. **Why this rather than the source** No developer account to apply for, no app review, no per-endpoint quota to manage. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Ask for a handle's followers here, then ask the same agent for that brand's search traffic, its backlinks, or the people to contact — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/social/mcp for X plus Instagram, Reddit, Pinterest and YouTube; https://mcp.aisa.one/gtm/mcp for those plus Similarweb and Apollo.
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
X (formerly Twitter) posts, profiles, and search for AI agents. Free key, self-minted, no signup.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceLive X (Twitter) and web search for any coding agent through your existing Grok subscription. Exposes a grok_search MCP tool, so no X API key or X developer account is needed.20 npm30Apache 2.0
- AlicenseBqualityDmaintenanceEnables interacting with Twitter/X through natural language, including searching tweets, posting, sending DMs, and managing timelines via any MCP client.8MIT
- FlicenseNot gradedqualityDmaintenanceEnables real-time search of X (Twitter) posts, user timelines, and trends using either xAI's Responses API or the official X API v2.4-