playbooks

home / mcp / web research assistant mcp server

Web Research Assistant MCP Server

MCP server for SearXNG with 13 production-ready tools for web search, package info, GitHub integration, error translation, API docs, and more

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "elad12390-web-research-assistant": {
      "command": "uvx",
      "args": [
        "web-research-assistant"
      ],
      "env": {
        "EXA_API_KEY": "YOUR_EXA_API_KEY",
        "MCP_USAGE_LOG": "/home/user/.config/web-research-assistant/usage.json",
        "PIXABAY_API_KEY": "YOUR_PIXABAY_API_KEY",
        "SEARCH_PROVIDER": "auto",
        "SEARXNG_BASE_URL": "http://localhost:2288/search",
        "SEARXNG_MAX_RESULTS": "10",
        "MCP_MAX_RESPONSE_CHARS": "8000",
        "SEARXNG_MCP_USER_AGENT": "web-research-assistant/0.1",
        "SEARXNG_CRAWL_MAX_CHARS": "8000",
        "SEARXNG_DEFAULT_RESULTS": "5",
        "SEARXNG_DEFAULT_CATEGORY": "general"
      }
    }
  }
}

You are equipped with a comprehensive MCP server that provides web research and discovery capabilities. It combines a local SearXNG instance, Exa AI neural search, crawl4ai, and Pixabay access to offer federated web searches, code and content discovery, image search, crawling, and structured data extraction all through reusable MCP tools, resources, and prompts.

How to use

You interact with the Web Research Assistant MCP Server through an MCP client. Start the server using one of the recommended deployment methods, then connect your MCP client to the local or remote MCP endpoint. Once connected, invoke the available tools to search, analyze, extract, and compare information from the web and code repositories. Each tool expects a reasoning parameter to accompany your queries, and will return well-scoped results that you can quote or summarize in your research.

To begin, configure your MCP client to point at the server, then use the tools for targeted tasks such as finding code examples, locating API documentation, extracting structured data from pages, or checking the health of external services. You can combine multiple tools to build end-to-end research workflows, for example: search for recent tutorials, extract key data tables from a page, and compare two technologies side by side.

How to install

Prerequisites: ensure you have Python 3.10 or newer and a running SearXNG instance available at http://localhost:2288.

Option 1: Full Docker setup (recommended) This runs both SearXNG and the MCP server in containers.

./docker-start.sh

Option 2: Python plus Docker SearXNG Install the MCP server and configure your environment.

uvx web-research-assistant  # or: pip install web-research-assistant

Configure your MCP client (Claude Desktop) to connect to the MCP server. Example configuration ( Claude Desktop )

{
  "mcpServers": {
    "web-research-assistant": {
      "command": "uvx",
      "args": ["web-research-assistant"]
    }
  }
}

Additional setup and notes

If you want to wire a local installation into Claude Desktop or OpenCode, you can use the provided MCP client configurations shown for UVX or direct package execution. You can also enable the recommended SearXNG engines for code search and web search to improve results.

Configuration and usage notes

The server uses a set of environment variables to tailor behavior, including the SearXNG base URL, default category, and API keys for image and neural search providers. You can override defaults via environment variables as described in the configuration guide.

Troubleshooting and tips

Ensure SearXNG is reachable at the configured base URL. If you encounter issues with web searches, confirm that the expected search engines are enabled in SearXNG (GitHub, Stack Overflow, code-related engines, etc.). Check that API keys for Pixabay and Exa are available if you use image search or neural search features.

Notes on tools, resources, and prompts

The MCP server provides 13 tools for searching, crawling, extracting data, and comparing technologies. It also includes resources for direct lookups and reusable prompts for common workflows. You will use a reasoning parameter with each tool call to help categorize usage and enable analytics.

Security and best practices

Keep API keys secure and avoid exposing them in logs. When running in shared environments, limit external calls and monitor usage with the built-in analytics to detect unusual activity.

Available tools

web_search

Federated search across multiple engines via SearXNG returning 1ā€“10 ranked snippets with clickable URLs. Requires a reasoning parameter and optional max_results.

search_examples

Find code examples, tutorials, and articles optimized for technical content with time range filtering and content type controls.

search_images

Find high-quality royalty-free stock images via Pixabay with image_type and orientation filters; requires PIXABAY_API_KEY.

crawl_url

Extract the full article body or data from a URL with an optional character limit for quoting or data extraction.

package_info

Retrieve package metadata from npm, PyPI, crates.io, or Go including version, downloads, license, and dependencies.

package_search

Discover packages by keywords or functionality with optional results limit.

github_repo

Assess repository health, activity, stars, forks, and recent commits for GitHub projects.

translate_error

Find Stack Overflow solutions for errors and stack traces with language/framework auto-detection.

api_docs

Auto-discover and crawl official API documentation for any API and extract topics, parameters, and examples.

extract_data

Extract structured data from HTML pages (tables, lists, fields, JSON-LD) and return clean JSON.

compare_tech

Side-by-side comparison of 2ā€“5 technologies with popularity metrics and insights.

get_changelog

Fetch release notes and changelogs with breaking change detection and upgrade guidance.

check_service_status

Instant health checks for 25+ services with status, incidents, and component health.