MCP WebResearch
Provides web search capabilities via SearxNG meta search engine, enabling AI to perform web searches and retrieve JSON-formatted results.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP WebResearchsearch for top Python tutorials in 2024"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π§ 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:
Docker installed
Docker Compose installed
(Optional) Node.js β₯ 18 if you want to run it manually
β‘ Quick Setup (Recommended via Docker)
This is the easiest way to get everything running.
Clone this repository
git clone https://github.com/damameet14/mcp-webresearch.git cd mcp-webresearchBuild and start the container
docker-compose up -dThatβ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:
SearxNG launches in the background.
A small startup script (
start.sh) waits until SearxNG is responsive.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 (
-jsonformat).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 toolslist_permanent_screenshotsA
List all permanently saved screenshots
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Filename of the permanent screenshot to read |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index of screenshot in current session to save permanently |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| savePermanently | No | Whether to save screenshot permanently |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to visit | |
| cookies | No | Optional array of cookies to inject into the browser context | |
| takeScreenshot | No | Whether to take a screenshot | |
| savePermanently | No | Whether to save screenshot permanently |
TDQS
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.
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.
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.
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.
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.
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.
6 tool updates
v0.1.0- First observed
list_permanent_screenshots - First observed
read_permanent_screenshot - First observed
save_screenshot_permanently - First observed
search_web - First observed
take_screenshot - First observed
visit_page
TDQS
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
An MCP server that gives your AI access to the source code and docs of all public github repos
An MCP server that integrates with Discord to provide AI-powered features.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server implementation that integrates the SearXNG API for powerful web search capabilities and uses @missionsquad/puppeteer-scraper to read and process live web content.216 npm1MIT
- AlicenseNot gradedqualityDmaintenanceAn 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 npmMIT
- AlicenseNot gradedqualityCmaintenanceMCP server for web search and content extraction using DuckDuckGo or SearXNG, with Playwright-based fetching and LLM-powered data extraction.139MIT
- AlicenseAqualityDmaintenanceA self-hosted MCP server that gives AI agents deep internet research capabilities β no API keys required, powered by SearxNG, Playwright, and Docker.453 npmISC