A FastMCP server that gives LLMs real-time web access — search engines, social platforms, academic databases, and developer tools, all in one MCP interface.

Full setup guide → README.md — covers prerequisites, all install options (uvx, permanent, dev), step-by-step config for each provider (X cookies, GitHub PAT, Exa), usage examples, and troubleshooting.

• Getting Started
• Tools Reference
• Design Decisions
• Plugin
• Development

• Python 3.11+
• uv — install it with curl -LsSf https://astral.sh/uv/install.sh | sh

Run without installing (uvx) — add to your MCP client config:

{
  "mcpServers": {
    "web-search": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sydasif/web-search-mcp.git", "web-search-mcp"]
    }
  }
}

Or install globally:

uv tool install git+https://github.com/sydasif/web-search-mcp.git

Most tools work out of the box. Only set these if you need the corresponding feature:

Tip: Export these in the same shell where the MCP server runs. See the README for detailed setup guides (X cookie extraction, GitHub PAT, Exa signup).

Once running, try:

search_web(query="current weather in Tokyo")

The server exposes 9 tools across 10 data sources. All are keyless unless noted.

Chaining tools gives better results than using a single one:

• fetch_page Bot Detection: Uses an auto backend (tries httpx → falls back to curl with TLS impersonation). If Cloudflare blocks you, try backend="curl".
• search_arxiv Upstream: arXiv API occasionally returns HTTP 503 during maintenance — retry after a few minutes.

The project is built for low-friction expansion. Each search engine or utility is an isolated module, preventing cross-module bugs.

Each tool is a standalone function in its own module. A bug in the Reddit parser won't crash GitHub search.

All inputs and outputs validated via Pydantic. The LLM receives consistent data shapes, reducing hallucination and client-side parsing errors.

Every tool returns a consistent ErrorResponse via _utils/formatting.py, so the LLM can distinguish auth failures from rate limits and pivot accordingly.

Most tools (Reddit, HN, Wikipedia, arXiv, DuckDuckGo) work with zero configuration. Auth is required only for X/Twitter and optional for Exa AI.

Reddit and GitHub use a tiered pipeline balancing latency against depth:

• Quick: Raw search results only
• Default: Top results + basic metadata
• Deep: Full comment enrichment and threaded conversations

For Claude Code users, install as a plugin to get both the MCP tools and specialized research skills:

/plugin marketplace add sydasif/web-search-mcp
/plugin install web-search@sydasif-web-search-mcp
/reload-plugins

• /web-search:research — Autonomous multi-source research across 7+ platforms
• /web-search:debug — Evidence-based debugging using web search and Stack Overflow

• Imports: Absolute imports only
• Naming: snake_case for functions, PascalCase for classes
• Types: Modern union syntax (str | None)
• Errors: All tool errors wrapped in format_error() from _utils/formatting.py

1. Implement — Create a new module in search/, social/, or tools/
2. Register — Add @mcp.tool() in server.py
3. Validate — Define Pydantic models in _models/ if needed
4. Test — Add a corresponding test in tests/

• Commits: Conventional Commits (feat:, fix:, refactor:, test:, chore:)
• Pre-commit: Run uv run ruff check . && uv run pytest before pushing
• Branches: Use feature branches for all new work

Note: See CLAUDE.md in the repo for common commands (testing, linting, type checking).