{
  "markdown": "# 🚀 OneSearch MCP Server: Web Search, URL Discovery, Scraper & Content Prep\n\nA Model Context Protocol (MCP) server implementation that integrates with multiple search providers for web search, local browser search, URL discovery, and scraping capabilities with agent-browser.\n\n## Features\n\n- Web search, scrape, discover URLs, and preprocess content from websites.\n- Support multiple search engines and web scrapers: **SearXNG**, **Tavily**, **DuckDuckGo**, **Bing**, **Google**, **Zhipu (智谱)**, **Exa**, **Bocha (博查)**, **You.com**, etc.\n- **Local web search** (browser search), support multiple search engines: **Bing**, **Google**, **Baidu**, **Sogou**, etc.\n  - Use `agent-browser` for browser automation.\n  - Free, no API keys required.\n- **Enabled tools:** `one_search`, `one_scrape`, `one_map`, `one_extract`\n\n## Current Tool Surface\n\n- `one_search`\n  - Returns search results from the configured provider.\n- `one_map`\n  - Discovers links from a starting URL by loading the page in the browser and extracting links from its HTML.\n  - Supported input fields: `url`, `search`, `includeSubdomains`, `limit`.\n  - This is not a sitemap crawler; removed fields such as `ignoreSitemap` and `sitemapOnly` are rejected at the schema boundary.\n- `one_scrape`\n  - Scrapes one page and returns content selected by `formats`.\n  - Supported input fields: `url`, `formats`, `waitFor`, `timeout`, `skipTlsVerification`, `allowExecuteJavascript`, `actions`.\n  - Supported formats: `markdown`, `html`, `rawHtml`, `links`, `screenshot`, `screenshot@fullPage`.\n  - Supported bounded pre-scrape actions: `wait`, `click`, `write`, `press`, `scroll`.\n  - Advanced pre-scrape action: `executeJavascript`. If `actions` contains `executeJavascript`, you must set `allowExecuteJavascript: true`.\n  - `actions` run serially before content capture and fail fast on the first action error.\n  - Removed fields such as `onlyMainContent`, `extract`, and `location` are rejected at the schema boundary.\n- `one_extract`\n  - Accepts only `urls` and returns preprocessed text blocks for downstream tools or models.\n\n## Migration from v1.1.0 and Earlier\n\n**Breaking Changes in v1.1.0:**\n\n- **Firecrawl Removed**: The Firecrawl integration has been removed in favor of `agent-browser`, which provides similar functionality without requiring external API services.\n- **New Browser Requirement**: You must install Chromium browser (see Prerequisites section).\n- **Environment Variables**: `FIRECRAWL_API_URL` and `FIRECRAWL_API_KEY` are no longer used.\n\n**What Changed:**\n\n- `one_scrape` and `one_map` now use `agent-browser` instead of Firecrawl\n- `one_extract` now preprocesses multi-URL page content for downstream analysis instead of performing built-in LLM extraction\n- All browser-based operations are now handled locally, providing better privacy and no API costs\n\n**Migration Steps:**\n\n1. Install Chromium browser (see Prerequisites)\n2. Remove `FIRECRAWL_API_URL` and `FIRECRAWL_API_KEY` from your environment variables\n3. Update to the latest version: `npm install -g one-search-mcp@latest`\n\n## Prerequisites\n\n**Browser Requirement**: This server uses `agent-browser` for web scraping and local search, which requires a Chromium-based browser.\n\n**Good News**: The server will automatically detect and use browsers already installed on your system:\n\n- ✅ Google Chrome\n- ✅ Microsoft Edge\n- ✅ Chromium\n- ✅ Google Chrome Canary\n\n**If you don't have any of these browsers installed**, you can:\n\n```bash\n# Option 1: Install Google Chrome (Recommended)\n# Download from: https://www.google.com/chrome/\n\n# Option 2: Install Microsoft Edge\n# Download from: https://www.microsoft.com/edge\n\n# Option 3: Install Chromium via agent-browser\nnpx agent-browser install\n\n# Option 4: Install Chromium directly\n# Download from: https://www.chromium.org/getting-involved/download-chromium/\n```\n\n## Installation\n\n### Using Claude Code CLI (Recommended)\n\n```bash\n# Add to Claude Code with default settings (local search)\nclaude mcp add one-search-mcp -- npx -y one-search-mcp\n\n# Add with custom search provider (e.g., SearXNG)\nclaude mcp add one-search-mcp -e SEARCH_PROVIDER=searxng -e SEARCH_API_URL=http://127.0.0.1:8080 -- npx -y one-search-mcp\n\n# Add with Tavily API\nclaude mcp add one-search-mcp -e SEARCH_PROVIDER=tavily -e SEARCH_API_KEY=your_api_key -- npx -y one-search-mcp\n```\n\n### Manual Installation\n\n```bash\n# Install globally (Optional)\nnpm install -g one-search-mcp\n\n# Or run directly with npx\nnpx -y one-search-mcp\n```\n\n### Local Debugging with MCP Inspector\n\nUse the official MCP Inspector to interactively test tools, resources, and prompts against this server during local development.\n\n```bash\n# Inspect the TypeScript source entrypoint\nnpm run inspector\n\n# Inspect the built server entrypoint\nnpm run inspector:build\n\n# Example with explicit environment variables\nALLOW_PRIVATE_NETWORK=true SEARCH_PROVIDER=local npm run inspector\n```\n\n### Using Docker\n\nDocker image includes all dependencies (Chromium browser) pre-installed, no additional setup required.\n\n**Pull the image:**\n\n```bash\n# From GitHub Container Registry\ndocker pull ghcr.io/yokingma/one-search-mcp:latest\n\n# Or from Docker Hub\ndocker pull zacma/one-search-mcp:latest\n```\n\n**Configure with Claude Desktop:**\n\n```json\n{\n  \"mcpServers\": {\n    \"one-search-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"ghcr.io/yokingma/one-search-mcp:latest\"],\n      \"env\": {\n        \"SEARCH_PROVIDER\": \"local\"\n      }\n    }\n  }\n}\n```\n\n**With custom search provider:**\n\n```json\n{\n  \"mcpServers\": {\n    \"one-search-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"SEARCH_PROVIDER=tavily\",\n        \"-e\", \"SEARCH_API_KEY=your_api_key\",\n        \"ghcr.io/yokingma/one-search-mcp:latest\"\n      ]\n    }\n  }\n}\n```\n\n## Environment Variables\n\n### Search Provider\n\n- **SEARCH_PROVIDER** (Optional): The search provider to use, supports `searxng`, `duckduckgo`, `bing`, `tavily`, `google`, `zhipu`, `exa`, `bocha`, `ydc`, `local`, default is `local`.\n- **SEARCH_API_URL** (Optional): The URL of the SearxNG API, or Google Custom Search Engine ID for `google`.\n- **SEARCH_API_KEY** (Optional): The API key for the search provider, required for `tavily`, `bing`, `google`, `zhipu`, `exa`, `bocha`.\n- **YDC_API_KEY** (Optional): You.com API key for `SEARCH_PROVIDER=ydc`.\n\n```ts\n// supported search providers\nexport type SearchProvider = 'searxng' | 'duckduckgo' | 'bing' | 'tavily' | 'google' | 'zhipu' | 'exa' | 'bocha' | 'ydc' | 'local';\n```\n\n### Browser Network Security\n\n- **ALLOW_PRIVATE_NETWORK** (Optional): Set to `true` to allow browser-backed tools (`one_scrape`, `one_map`, `one_extract`) to access private, loopback, and link-local network targets. Defaults to `false`.\n\nUse `ALLOW_PRIVATE_NETWORK=true` only in trusted deployments. When enabled, prompt injection or untrusted tool inputs can make the MCP process fetch internal services that are otherwise blocked by default.\n\n### Search Provider Configuration\n\n| Provider | API Key Required | API URL Required | Notes |\n|----------|-----------------|------------------|-------|\n| `local` | No | No | Free, uses browser automation |\n| `duckduckgo` | No | No | Free, no API key needed |\n| `searxng` | Optional | Yes | Self-hosted meta search engine |\n| `bing` | Yes | No | [Bing Search API](https://learn.microsoft.com/en-us/previous-versions/bing/search-apis/bing-web-search/create-bing-search-service-resource) |\n| `tavily` | Yes | No | [Tavily API](https://tavily.com/) |\n| `google` | Yes | Yes (Search Engine ID) | [Google Custom Search](https://developers.google.com/custom-search/v1/overview) |\n| `zhipu` | Yes | No | [智谱 AI](https://bigmodel.cn/dev/api/search-tool/web-search) |\n| `exa` | Yes | No | [Exa AI](https://exa.ai/) |\n| `bocha` | Yes | No | [博查 AI](https://open.bochaai.com/) |\n| `ydc` | Yes | No | [You.com Search](https://you.com/platform) |\n\n## Configuration for Other MCP Clients\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"one-search-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"one-search-mcp\"],\n      \"env\": {\n        \"SEARCH_PROVIDER\": \"local\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to your `mcp.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"one-search-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"one-search-mcp\"],\n      \"env\": {\n        \"SEARCH_PROVIDER\": \"local\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to your `./codeium/windsurf/model_config.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"one-search-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"one-search-mcp\"],\n      \"env\": {\n        \"SEARCH_PROVIDER\": \"local\"\n      }\n    }\n  }\n}\n```\n\n## Self-hosting SearXNG (Optional)\n\nIf you want to use SearXNG as your search provider, you can deploy it locally using Docker:\n\n**Prerequisites:**\n\n- Docker installed and running (version 20.10.0 or higher)\n- At least 4GB of RAM available\n\n**Quick Start:**\n\n```bash\n# Clone SearXNG Docker repository\ngit clone https://github.com/searxng/searxng-docker.git\ncd searxng-docker\n\n# Start SearXNG\ndocker compose up -d\n```\n\nAfter deployment, SearXNG will be available at `http://127.0.0.1:8080` by default.\n\n**Configure OneSearch to use SearXNG:**\n\n```bash\n# Set environment variables\nexport SEARCH_PROVIDER=searxng\nexport SEARCH_API_URL=http://127.0.0.1:8080\n```\n\nFor more details, see the [official SearXNG Docker documentation](https://github.com/searxng/searxng-docker).\n\n## Troubleshooting\n\n### Browser not found error\n\nIf you see an error like \"Browser not found\", the server couldn't detect any installed Chromium-based browser. Please install one of the following:\n\n- **Google Chrome**: <https://www.google.com/chrome/>\n- **Microsoft Edge**: <https://www.microsoft.com/edge>\n- **Chromium**: <https://www.chromium.org/getting-involved/download-chromium/>\n\nOr install via agent-browser:\n\n```bash\nnpx agent-browser install\n```\n\n## License\n\nMIT License - see [LICENSE](./LICENSE) file for details.\n",
  "bytes": 10130,
  "sha": "772677eea025bb857c004c1d2d3228e78c2c8a9cde537a572074b0af310a97e2",
  "repo_slug": "yokingma/one-search-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yokingma_one_search_mcp_74efeef6/readme"
}