web-search-mcp

A comprehensiveModel Context Protocol (MCP)server built withFastMCPthat provides LLMs with real-time, high-fidelity access to the web. This server aggregates multiple search engines, social platforms, and developer tools into a single interface, allowing AI agents to perform deep research, track community sentiment, and analyze technical documentation.

Design docs →wiki— tool selection guide, decision matrix, recommended workflows, tools status & known quirks, plugin setup, and development standards.

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

Fastest startup times with a globally installed tool:

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

{ "mcpServers": { "web-search": { "command": "web-search-mcp" } } }

If you want to modify the code or contribute:

git clone https://github.com/sydasif/web-search-mcp.git cd web-search-mcp uv sync uv run web-search-mcp

Once the server is running, try a simple search:

search_web(query="current weather in Tokyo")

Most tools workout of the box with zero configuration. The following environment variables are only needed for premium or authenticated features.

The server detects your local session automatically.

export GITHUB_TOKEN="ghp_your_token_here"

- Sign up atxquik.aito get an API key.
- Export it:

export XQUIK_API_KEY="your_xquik_key"

export EXA_API_KEY="your_exa_key"

# Broad search search_web(query="Latest NVIDIA H200 benchmarks") # Targeted documentation search search_web(query="useEffect cleanup", domain="react.dev") # News with region filter search_web(query="elections", search_type="news", region="us-en", provider="exa") # Date-filtered search search_web(query="uv package manager", time_range="w", provider="auto") # Deep read a page fetch_page(url="https://docs.python.org/3/library/os.html")

# Track GitHub issues/PRs search_github(query="uv package manager") # Get full GitHub issue thread get_github_issue(url="https://github.com/astral-sh/uv/issues/1")

# Reddit discussions search_reddit(query="Best mechanical keyboards 2024", subreddits=["MechanicalKeyboards"]) # Hacker News technical discourse search_hackernews(query="MCP server architecture") # LinkedIn professional search search_linkedin(query="site reliability engineer", content_type="people") search_linkedin(query="machine learning startup", content_type="companies") search_linkedin(query="kubernetes devops", content_type="jobs") search_linkedin(query="AI agents", content_type="posts")

# arXiv paper search with field prefixes search_arxiv(query="au:Goodfellow AND cat:cs.LG") search_arxiv(query="transformer attention", sort_by="submitted_date") # Wikipedia background research search_wikipedia(query="Quantum computing")

web_search_mcp/ ├── server.py # Entry point: FastMCP init, @mcp.tool registrations ├── search/ # Search engine implementations │ ├── ddg.py # DuckDuckGo search + trafilatura page fetch │ └── exa.py # Exa SDK search & content fetch (lazy-init client) ├── social/ # Community platform integrations │ ├── github.py # GitHub Search API + gh CLI issue rendering │ ├── hackernews.py # Algolia HN API + comment enrichment │ ├── linkedin/ # LinkedIn search via DDG + Jina Reader │ │ ├── __init__.py # LinkedIn search tool registration │ │ └── client.py # DDG search + Jina Reader enrichment │ ├── reddit/ # RSS + Shreddit keyless pipeline │ │ ├── client.py # HTTP client with RSS parsing │ │ ├── parsers.py # RSS/HTML parsers │ │ └── shreddit.py # Shreddit comment enrichment │ └── x.py # X/Twitter search via Xquik API or vendored Bird CLI ├── tools/ # Specialized reference utilities │ ├── arxiv.py # arXiv paper search (Lucene field prefixes) │ └── wikipedia.py # Wikipedia MediaWiki API ├── _config/ # Settings, env vars, rate limits, depth tiers │ ├── settings.py # pydantic-settings (EXA_API_KEY, SEARCH_MCP_ prefix) │ └── limits.py # Per-platform quick/default/deep limits, timeouts ├── _http/ # Shared HTTP + SSRF protection │ └── client.py # validate_url, http_client, get_json_client ├── _models/ # Pydantic request/response models │ ├── requests.py # SearchRequest │ ├── responses.py # ErrorResponse, SearchResponse, PageResponse │ └── types.py # Depth, ResponseFormat, SearchType, FetchOutputFormat ├── _utils/ # Shared helpers │ ├── formatting.py # Markdown formatters, date/epoch utils │ ├── rate_limiter.py # Token-bucket rate limiter │ └── scoring.py # Relevance scoring └── vendor/ # Vendored third-party tools └── bird-search/ # Node.js CLI for X/Twitter search (fallback when XQUIK_API_KEY unset)

- Implement logicin the appropriate module (search/,social/, ortools/)
- Define modelsin_models/(request/response types)
- Register inserver.pyusing@mcp.tooldecorator with a clear docstring (serves as the tool's description for the LLM)

# Run all tests uv run pytest # Run a single test file uv run pytest tests/test_module.py # Run a specific test uv run pytest tests/test_module.py::test_function_name # Run with coverage uv run pytest --cov=web_search_mcp

- Fork the repository.
- Create a feature branch:git checkout -b feat/my-new-tool
- Ensure all tests pass:uv run pytest
- Submit a pull request with a detailed description of the changes.

This project is licensed under theMIT License.

Enhances LLM responses with factual, real-time web content using Jina AI's grounding capabilities.