MCP Browser

A Model Context Protocol (MCP) server that provides web search and browsing capabilities. Built with Rust using Axum and Tokio for high performance and reliability.

Description

MCP Browser is a lightweight server that exposes web search and browsing functionality through the Model Context Protocol. It allows AI models to search the internet using multiple search engines and browse web pages, converting HTML content to clean markdown format.

Features

• Multiple Search Engines: SearXNG, Wikipedia, DuckDuckGo, and StackOverflow
• Web Browsing: Fetch and convert web pages to markdown
• File Download: Download files from URLs to specified directories
• HTML to Markdown: Clean conversion with content extraction
• MCP Protocol: Full compatibility with Model Context Protocol
• High Performance: Built with Rust, Tokio, and Axum

Endpoints

Discovery Endpoints

• GET /.well-known/mcp - MCP server discovery
• GET /discovery - Alternative discovery endpoint

MCP Endpoints

• POST /message - JSON-RPC message handling
• GET /sse - Server-Sent Events for keep-alive

Available Tools

search

Search the internet using various search engines.

{
  "query": "your search query",
  "engine": "searxng|wikipedia|duckduckgo|stackoverflow"
}

list_search

List all available search engines and their descriptions.

browse

Browse a web page and convert HTML to markdown.

{
  "url": "https://example.com"
}

How to Use

1. Installation

From Source

git clone <repository-url>
cd mcp-browser
cargo build --release

Using Docker

git clone <repository-url>
cd mcp-browser
docker build -t mcp-browser .

2. Running the Server

Using Cargo

# Default (127.0.0.1:3002)
cargo run

# Custom bind address
BIND_ADDRESS=0.0.0.0:8080 cargo run

Using Docker

# Default port
docker run -p 3002:3002 mcp-browser

# Custom port
docker run -p 8080:8080 -e BIND_ADDRESS=0.0.0.0:8080 mcp-browser

3. Using with MCP Client

The server exposes MCP-compatible endpoints that can be consumed by any MCP client:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "rust programming",
      "engine": "searxng"
    }
  }
}

4. Discovery

Visit http://127.0.0.1:3002/.well-known/mcp to see the server capabilities and available tools.

Configuration

Environment Variables

• BIND_ADDRESS - Server bind address (default: 127.0.0.1:3002)
• RUST_LOG - Log level (default: info)
• SEARXNG_INSTANCE - SearXNG instance URL (default: https://search.sapti.me)

Search Engine Configuration

The default search engine is SearXNG. You can specify a different engine in each search request or configure your preferred SearXNG instance using the SEARXNG_INSTANCE environment variable.

Configuring SearXNG Instance

To use a different SearXNG instance:

SEARXNG_INSTANCE=https://your-searxng-instance.com cargo run

Popular public SearXNG instances include:

• https://search.sapti.me (default)
• https://searx.be
• https://search.bus-hit.me
• https://searx.work

Supported Content Types

• text/html - Converted to markdown
• text/plain - Returned as-is
• text/markdown - Returned as-is
• application/json - Returned as-is
• application/yaml - Returned as-is
• text/yaml - Returned as-is

Examples

Search Example

curl -X POST http://127.0.0.1:3002/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "query": "Model Context Protocol",
        "engine": "wikipedia"
      }
    }
  }'

Browse Example

curl -X POST http://127.0.0.1:3002/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "browse",
      "arguments": {
        "url": "https://github.com"
      }
    }
  }'

Development

Requirements

• Rust 1.70+
• Cargo

Building

cargo build

Testing

cargo test

Linting

cargo clippy
cargo fmt

License

This project is licensed under the ISC License - see the LICENSE file for details.