freeWeb MCP Server

A lightweight MCP (Model Context Protocol) server providing web search and page content extraction tools powered by DuckDuckGo.

Tools

• web_search - Search the web using DuckDuckGo, returning title, URL, and snippet for each result.

• web_visit - Visit a URL and extract its page content in various formats (markdown, plain text, rich text).

Quick Start

1. Create the conda environment

conda create -n mcp python=3.12
conda activate mcp
pip install -r requirements.txt

2. Run the server

python main.py              # HTTP mode on http://127.0.0.1:8101/mcp
python main.py --stdio      # Stdio mode (for MCP clients)

3. Run tests

python test_server.py

Browser-based MCP Clients

MCP 2.x returns a plain Starlette app with no built-in CORS handling. When connecting from a browser-based MCP client (e.g., at http://127.0.0.1:8080), add CORSMiddleware:

from starlette.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://127.0.0.1:8080"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
    expose_headers=["Mcp-Session-Id", "Mcp-Protocol-Version"],
)

The SDK intentionally provides no opinionated middleware — auth, rate limiting, and CORS are left to the user.

Project Structure

freeWeb/
├── main.py              # Server entry point (HTTP + stdio modes)
├── test_server.py       # Test suite (run with: python test_server.py)
└── tools/
    ├── __init__.py
    ├── search.py        # web_search tool
    └── visit.py         # web_visit tool

MCP Client Configuration

Stdio transport

{
  "mcpServers": {
    "freeWeb": {
      "command": "conda",
      "args": ["run", "-n", "mcp", "python", "/path/to/freeWeb/main.py", "--stdio"]
    }
  }
}

HTTP transport (browser clients)

Connect your browser-based MCP client to http://127.0.0.1:8101/mcp with CORS configured as shown above.

Requirements

See requirements.txt. Test uses starlette (TestClient), which is a transitive dependency of mcp.