Skip to main content
Glama
damameet14
by damameet14

🧠 MCP WebResearch

An AI-ready MCP Server that performs intelligent web searches using SearxNG and Playwright β€” all containerized for one-step setup. This project provides both manual and Docker installation options for developers and Cline users.


πŸš€ Features

  • πŸ” Integrated SearxNG meta search engine

  • 🧭 Web automation via Playwright

  • 🐳 One-command Docker setup (runs MCP + SearxNG together)

  • 🧩 Supports JSON search results for easy AI processing

Related MCP server: searxng-mcp

Newly added features

  • Now you can save the screenshots in your permanent memory. Just tell your AI to save the screen shot permanently.

  • You can ask the AI to list the screenshots. This will give you the path at which the screenshots are saved.

  • More features are incoming...


🧰 Prerequisites

Before starting, ensure you have:


This is the easiest way to get everything running.

  1. Clone this repository

    git clone https://github.com/damameet14/mcp-webresearch.git
    cd mcp-webresearch
  2. Build and start the container

    docker-compose up -d

    That’s it! πŸŽ‰

    • This automatically installs all dependencies.

    • Starts SearxNG on port 8080.

    • Waits until it’s ready.

    • Then launches your MCP server.


πŸ”§ Cline MCP Configuration

Once the container is running, edit your mcp_settings.json:

"mcpServers": {
  "webresearch": {
    "command": "docker",
    "args": ["exec", "-i", "mcp-webresearch", "node", "/app/index.js"]
  }
}

This connects Cline directly to your running container.


🧱 Manual Setup (Without Docker)

If you don’t want to use Docker:

# Clone this repo
git clone https://github.com/damameet14/mcp-webresearch.git
cd mcp-webresearch

# Install MCP dependencies
npm install

# Clone and setup SearxNG
git clone https://github.com/searxng/searxng.git
cd searxng
make install

# Enable JSON output (important)
# Add "-json" to line 78 of searx/settings.yml manually

# Start SearxNG
make run # Note that you will have to start the searxng instance everytime you want to use the mcp server.

I am working on making "no docker" setup too a one command setup. But for now, I recommend going with Docker or go through this tiring process.

πŸ”§ Cline MCP Configuration (for manual setup)

Once the container is running, edit your mcp_settings.json:

"mcpServers": {
  "webresearch": {
    "command": "node",
    "args": ["<path_to>/mcp-webresearch/index.js"]
  }
}

🧠 How It Works

Inside the container:

  1. SearxNG launches in the background.

  2. A small startup script (start.sh) waits until SearxNG is responsive.

  3. Then your MCP server (index.js) starts.

Both processes share the same network and communicate via localhost:8080.


🧩 Project Structure

mcp-webresearch/
β”œβ”€β”€ index.js
β”œβ”€β”€ package.json
β”œβ”€β”€ Dockerfile
β”œβ”€β”€ docker-compose.yml
β”œβ”€β”€ start.sh
└── etc...

⚠️ Notes

  • The default SearxNG config is patched automatically to support JSON output (-json format).

  • The container is lightweight and will stay idle when unused.

  • You can stop it anytime to free memory.


πŸ’‘ Future Plans

  • Add Windows-compatible setup

  • Publish image to Docker Hub and MCP Registry for AI code editors

  • Add more tools


Compatibility

  • This is intended for Linux and MacOS.

  • But if you want to use it on windows, you can do so with wsl (You can download it from Microsoft Store)

πŸ§‘β€πŸ’» Author

Meet Dama (@damameet14) Creator of the MCP WebResearch Server


Available Tools

6 tools
list_permanent_screenshotsA

List all permanently saved screenshots

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It clearly indicates a read-only listing operation, but it does not disclose the return format, pagination, or any limitations. This is adequate for a simple list tool but lacks richer behavioral context.

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 a single clear sentence with no extraneous words. It is appropriately concise and front-loads the core purpose.

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 tool is very simple with no parameters and no output schema. The description states the core behavior but does not specify what the returned list items contain (e.g., IDs, filenames). This is a minor gap, but given the tool's simplicity, the description is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool accepts zero parameters, so the baseline is 4. The description correctly implies that no arguments are needed, and there is nothing else to document.

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 uses the specific verb 'list' and identifies the resource as 'all permanently saved screenshots', making the tool's function immediately obvious. It is clearly distinct from sibling tools like take_screenshot (captures) and read_permanent_screenshot (reads a single screenshot).

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 (when you need a list of saved screenshots) but does not explicitly state when to use this tool versus alternatives or direct the agent to sibling tools. There is no mention of exclusions or prerequisite operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_permanent_screenshotB

Read a specific permanent screenshot

ParametersJSON Schema
NameRequiredDescriptionDefault
filenameYesFilename of the permanent screenshot to read

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only says 'Read', implying a safe read operation, but does not disclose what happens if the file is missing, whether it reads from local storage, or any side effects. Minimal behavioral insight.

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?

A single concise sentence that is front-loaded and contains no wasteful words. It is appropriately sized for a simple read operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, yet the description does not explain return values (e.g., image content or path). It also omits any context about how to obtain the filename or that the screenshot must already exist. The description is too terse for full completeness given these gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description for 'filename'. The tool description adds only the word 'specific', which is redundant. Baseline 3 is appropriate since the schema handles parameter meaning adequately.

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 clearly states the action (read) and resource (specific permanent screenshot). It distinguishes from sibling tools like take_screenshot (create) and list_permanent_screenshots (list), making it unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., using list_permanent_screenshots to obtain a filename) or contexts where this tool is preferable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

save_screenshot_permanentlyB

Save a screenshot from current session permanently

ParametersJSON Schema
NameRequiredDescriptionDefault
indexYesIndex of screenshot in current session to save permanently

TDQS

B3/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full behavioral burden, but it discloses no side effects, permissions, or downstream consequences. 'Permanently' implies persistence but does not clarify whether the session screenshot is moved, copied, or deleted, nor does it mention overwrite behavior.

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 a single, grammatically complete sentence with no redundant words. It front-loads the core action and resource, earning high marks for conciseness and structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description gives the minimum viable statement of purpose, but it omits behavioral context such as what constitutes 'permanent', whether the operation is reversible, or what the tool returns on success. Given the lack of annotations, this is insufficient for an AI agent to use the tool confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes the single parameter 'index' with 100% coverage, so the description need not add more. The description itself adds no additional semantic meaning beyond the schema, hence the baseline score of 3.

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 uses the specific verb 'save' with a clear resource ('a screenshot from current session') and the adverb 'permanently' distinguishes it from temporary session screenshots. This clearly separates it from sibling tools like take_screenshot and list_permanent_screenshots.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention that take_screenshot creates session screenshots or that list/read_permanent_screenshots handle retrieval, leaving the agent to infer the intended workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_webA

Search the web using Searxng

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the search action and engine, but does not disclose what the tool returns (e.g., list of results, URLs), whether it performs network requests, or any limitations. This is insufficient for an agent to anticipate the tool's behavior.

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 a single concise sentence that is front-loaded with the key action and resource. Every word contributes, and there is no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one required parameter, no output schema), the description is minimally adequate but leaves gaps. It does not explain the return format or how results relate to sibling tools like visit_page, which would be useful context. However, for a basic search operation, the core purpose is clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage for the 'query' parameter with a clear description ('Search query'), so the schema already documents the parameter effectively. The tool description adds no additional semantic meaning beyond the schema.

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 clearly states the action ('Search the web') and the backend ('using Searxng'), making it distinct from sibling tools like visit_page and take_screenshot which handle page navigation and captures. The verb and resource are specific and 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 this tool is for performing web searches but does not explicitly state when to use it versus alternatives, nor does it mention exclusions or prerequisites. The intended use is inferable from the tool name and sibling context, but no direct guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

take_screenshotC

Take a screenshot of the current page

ParametersJSON Schema
NameRequiredDescriptionDefault
savePermanentlyNoWhether to save screenshot permanently

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action but does not disclose whether the screenshot is saved, returned, or temporary, nor any side effects. The presence of the 'savePermanently' parameter hints at behavior, but the description itself lacks transparency about the tool's outcomes.

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 a single, front-loaded sentence with no unnecessary words. It immediately conveys the core action and resource, making it highly concise and appropriately structured for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has only one parameter and no output schema, but the description still leaves important context ambiguous. Given the sibling 'save_screenshot_permanently', it's unclear whether this tool saves temporarily, returns raw data, or behaves differently. The description does not explain what happens after taking the screenshot, making it incomplete for an agent to choose correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema includes one boolean parameter 'savePermanently' with a description, achieving 100% schema description coverage. The tool description adds no additional meaning about the parameter, but the schema already provides sufficient semantics, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Take a screenshot') and the target ('current page'). However, it does not differentiate from the sibling tool 'save_screenshot_permanently', which might also take a screenshot but with permanent saving. The verb and resource are specific, but sibling distinction is missing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives like 'save_screenshot_permanently' or 'visit_page'. No context, exclusions, or alternative suggestions are provided, leaving the agent to infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

visit_pageC

Visit a webpage and extract its content

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL to visit
cookiesNoOptional array of cookies to inject into the browser context
takeScreenshotNoWhether to take a screenshot
savePermanentlyNoWhether to save screenshot permanently

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full responsibility for behavioral disclosure. It fails to mention side effects such as taking or permanently saving screenshots, or that it injects cookies. The phrase 'extract its content' implies read-only access, which is potentially misleading given the screenshot capabilities.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no fluff, placing the core action first. However, it omits any mention of additional functionality like screenshots, which slightly underrepresents the tool's scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool can take screenshots and save them permanently, yet the description focuses only on 'extract its content'. There is no output schema, and the return format is never explained. For a tool with multiple modes and side effects, this description is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (url, cookies, takeScreenshot, savePermanently) are already described in the schema. The description adds no extra meaning, so the baseline of 3 applies.

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 clearly states the tool's function: 'Visit a webpage and extract its content'. This uses a specific verb and resource, distinguishing it from siblings like 'search_web' (which finds pages) and 'take_screenshot' (which only captures the screen).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives. It does not mention cases like accessing a specific URL directly vs. searching, nor does it note any prerequisites or exclusions.

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. 6 tool updatesv0.1.0
    • First observedlist_permanent_screenshots
    • First observedread_permanent_screenshot
    • First observedsave_screenshot_permanently
    • First observedsearch_web
    • First observedtake_screenshot
    • First observedvisit_page

TDQS

A3.6/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a distinct purpose: searching, visiting pages, taking screenshots, saving screenshots, listing saved screenshots, and reading them. There is no overlap or ambiguity between the tools.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern, such as search_web, visit_page, and take_screenshot. The naming is uniform and predictable across the set.

Tool Count5/5

With 6 tools, the server is well-scoped for web research. Each tool serves a clear function without redundancy or excessive bloat, and the count is appropriate for the domain.

Completeness4/5

The tool set covers the core workflow of searching, visiting, capturing, and persisting web content. Minor gaps exist, such as the absence of a delete operation for permanent screenshots or page interaction beyond simple visiting, but these are not critical for the stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that wraps a local SearXNG instance to provide private, customizable web search capabilities. It enables AI assistants to perform queries with support for specific parameters like results limits, language, and time ranges.
    109 npm
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for web search and content extraction using DuckDuckGo or SearXNG, with Playwright-based fetching and LLM-powered data extraction.
    139
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    A self-hosted MCP server that gives AI agents deep internet research capabilities β€” no API keys required, powered by SearxNG, Playwright, and Docker.
    4
    53 npm
    ISC