You can run the OneSearch MCP Server to perform web search, local browser search, scraping, and extraction using a flexible set of providers. This MCP server lets you mix and match search engines and scrapers, automate browser-based tasks, and access tools for searching, scraping, mapping, and extracting data all from a single, local, privacy-friendly setup.

How to use

You use an MCP client to connect to the OneSearch MCP Server. The server exposes multiple tools that you can invoke via the MCP client: one_search to perform web searches, one_scrape to extract content from pages, one_map for structured browser-based mapping, and one_extract to gather structured data from multiple URLs. You configure a preferred search provider by setting environment variables and then issue requests through your MCP client to run searches, scrapes, or extractions. You can also run local browser searches using the agent-browser workflow, which operates directly on your machine without external API costs.

How to install

Follow these steps to install and run the OneSearch MCP Server. Make sure you meet the prerequisites and then install using your preferred method.

# Prerequisites
- A Chromium-based browser (required for agent-browser) or ensure you can install one.
- Node.js and npm installed on your system (or use Docker for a preconfigured image).

# Option A: Install via Claude Code CLI (recommended for quick setup)

claude mcp add one-search-mcp -- npx -y one-search-mcp

# Optional: Add with a specific search provider

claude mcp add one-search-mcp -e SEARCH_PROVIDER=searxng -e SEARCH_API_URL=http://127.0.0.1:8080 -- npx -y one-search-mcp

# Option B: Global installation (npm)

npm install -g one-search-mcp npx -y one-search-mcp

# Docker (preconfigured with Chromium)

docker pull ghcr.io/yokingma/one-search-mcp:latest

# Docker configuration example for Claude Desktop (local search)

{ "mcpServers": { "one-search-mcp": { "command": "docker", "args": ["run", "-i", "--rm", "ghcr.io/yokingma/one-search-mcp:latest"], "env": { "SEARCH_PROVIDER": "local" } } } }

# Custom search provider (example)

{ "mcpServers": { "one-search-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SEARCH_PROVIDER=tavily", "-e", "SEARCH_API_KEY=YOUR_API_KEY", "ghcr.io/yokingma/one-search-mcp:latest" ] } } }

# Self-hosted SearXNG (optional) (local deployment)

Prerequisites: Docker installed and at least 4GB RAM

git clone https://github.com/searxng/searxng-docker.git cd searxng-docker docker compose up -d

# Configure OneSearch to use SearXNG

export SEARCH_PROVIDER=searxng export SEARCH_API_URL=http://127.0.0.1:8080

## Migration from v1.1.0 and Earlier

If you are upgrading from v1.1.0 or earlier, you should adjust to the new browser-based workflow and remove API dependencies that have been retired. The new approach relies on local browser automation and the agent-browser tool for all browser-based operations.

Migration steps include installing a Chromium-based browser, removing obsolete API keys, and updating to the latest MCP package.

## Prerequisites

This server uses agent-browser for web scraping and local search, which requires a Chromium-based browser. The server will automatically detect and use browsers already installed on your system, such as Google Chrome, Microsoft Edge, Chromium, or Google Chrome Canary. If none are installed, you can install one of the following:

Option 1: Install Google Chrome (Recommended)

Download from: https://www.google.com/chrome/

Option 2: Install Microsoft Edge

Download from: https://www.microsoft.com/edge

Option 3: Install Chromium via agent-browser

npx agent-browser install

Option 4: Install Chromium directly

Download from: https://www.chromium.org/getting-involved/download-chromium/

"""

## Self-hosting SearXNG (Optional)

If you want to use SearXNG as your search provider, you can deploy it locally using Docker. This requires Docker and sufficient RAM. After deployment, SearXNG will be available at http://127.0.0.1:8080 by default.

Quick Start for SearXNG (Docker)

git clone https://github.com/searxng/searxng-docker.git
cd searxng-docker
docker compose up -d

Configuration for Other MCP Clients

Configure your MCP client to point at OneSearch MCP Server by using the provided command and environment examples. The snippets show how to set the provider to local or a custom provider and how to start the server through your client.

Troubleshooting

If you encounter a browser not found error, ensure a Chromium-based browser is installed or install via agent-browser with the command shown in prerequisites.

License

MIT License - see LICENSE file for details.

Available tools

one_search

Performs web searches across configured providers and aggregates results.

one_scrape

Scrapes content from websites and extracts meaningful data.

one_map

Provides browser-based mapping and structured data collection via local browser automation.

one_extract

Extracts structured data from multiple URLs, enabling data consolidation.