X-deepresearch

Turn X conversations into research you can track and compare.

English · 日本語

Search posts · Track 90 days · Compare topics · Export reports

Quick start

What you need: Python 3.12+, uv, Git and your own X session. Use a terminal with hidden input; Codex CLI is needed for automatic Codex registration.

uvx --from git+https://github.com/taxma604/X-deepresearch x-deepresearch-setup

The setup securely collects your own auth_token and ct0 (where to find them), saves them locally, sets search permissions, and registers the MCP server in Codex. Credentials are never included in command arguments or shared with the project author.

Claude Code, Claude Desktop, Cursor or VS Code? Run setup with --client none, then follow the MCP client instructions.

Distribution: Install from GitHub; PyPI is not yet supported. Validation results.

Full installation and privacy notes · Client setup · 日本語の導入手順

Related MCP server: Grok X Insights MCP Server

Research ideas to try

1. Has the buzz already peaked?

Investigate X posts about "[topic]" over the past 30 days. Find the peak day, compare the first and last seven days, and show representative posts with their URLs. Is the observed conversation growing or fading?

2. Was it already being discussed before launch?

Look at X posts about "[product]" from seven days before to seven days after its announcement. Put the early discussions in chronological order and compare daily post counts before and after the announcement. Include original post links.

3. What was X discussing before a stock surged?

Research posts about "[company or ticker]" from seven days before to seven days after its sharp price rise. Show when discussions began to increase, observed daily post counts, and relevant post links. Distinguish the timeline from any unproven claim that X activity caused the price move.

Replace the bracketed placeholders with your subject. These prompts use existing search, daily-count and comparison tools; the AI assistant organizes the findings. More research workflows (日本語).

Why X-deepresearch?

Most X automation tools focus on posting or managing accounts, and many MCP wrappers focus on fetching individual posts. X-deepresearch focuses on a different workflow: ask an AI agent to collect, count, compare, and audit the coverage of research results.

Research-first, not a posting bot. It does not publish posts, like, follow, send messages, perform sentiment analysis, or promise a complete archive of X. Coverage diagnostics indicate known retrieval gaps, not a guarantee that X returned all matching posts.

Available MCP tools

Results are bounded by configured limits and upstream availability. Start long studies asynchronously and poll their job_id. The synchronous daily-stats tool returns a bounded sample, not an exhaustive multi-week total.

Supported environments

• Codex CLI: interactive one-command onboarding and registration.

• Claude Code / Claude Desktop / Cursor / VS Code: local stdio MCP configuration guides.

• Other MCP hosts: any client implementing a compatible local stdio transport can attempt the documented configuration.

Local session files reside under ~/.config/x-deepresearch/ by default. SQLite restart recovery is opt-in via X_RESEARCH_JOB_DB. Security · Validation status · Troubleshooting.

Develop

git clone https://github.com/taxma604/X-deepresearch.git
cd X-deepresearch
uv sync --extra dev --locked
uv run --locked pytest -q
uv run --locked ruff check .

Automated tests use mock X clients and do not require an X account.

Contributing and project status

Documentation, client configuration fixes, robust aggregation, reproducible tests, and honest coverage reporting are welcome. Contributing · Changelog · Security · MIT License.

Package status: source version 0.3.0; not published on PyPI, with no hosted multi-user service. Source history has been separated from the original private development repository. Public release checklist.