MCP Web Tools

A Model Context Protocol (MCP) server that provides web search and fetch capabilities for AI assistants like Claude Code.

This is useful when you want your code-generation tool to make web requests directly from your machine, rather than having those requests proxied through an external server you don't control. The MCP server runs locally on your host, so all web requests originate from your own network.

Features

• web_search - Search the web using DuckDuckGo

  • Returns formatted results with titles, URLs, and snippets

  • Configurable result count and region

• web_fetch - Fetch and extract content from web pages

  • Automatic HTML-to-text conversion (removes scripts, styles, navigation)

  • JSON response formatting

  • Configurable timeout

Requirements

• Python 3.13+

• uv

Installation

Quick Install (Recommended)

# Clone the repository
git clone <repo-url>
cd mcp-web-tools

# Install globally and configure Claude Code
make install

This will:

1. Install mcp-web-tools as a global executable via uv tool install

2. Register the MCP server with Claude Code using claude mcp add

3. The executable will be available at ~/.local/bin/mcp-web-tools

Restart Claude Code after installation.

Manual Installation

# Install dependencies
uv sync

# Run directly from project
uv run mcp-web-tools

Makefile Targets

Claude Code Configuration

After running make install, you can verify the registration:

claude mcp list

The tools will be available in Claude Code as:

• mcp__web-tools__web_search

• mcp__web-tools__web_fetch

Manual Registration

If you prefer to register manually:

# User-wide (available in all projects)
claude mcp add --scope user web-tools mcp-web-tools

# Project-local (only current project)
claude mcp add --scope project web-tools mcp-web-tools

Alternative: Run from Project Directory

For development, you can register to run directly from the source:

claude mcp add --scope project web-tools uv run --directory /path/to/mcp-web-tools mcp-web-tools

Tool Reference

web_search

Search the web using DuckDuckGo.

Parameters:

Example response:

Search results for: python mcp server

1. Building MCP Servers in Python
   URL: https://example.com/article
   Learn how to build Model Context Protocol servers...

2. MCP Documentation
   URL: https://modelcontextprotocol.io/docs
   Official documentation for the Model Context Protocol...

web_fetch

Fetch the content of a web page.

Parameters:

Example response:

Content from https://example.com/article:

Building MCP Servers
This guide covers the basics of creating an MCP server...

Development

Running Tests

make test

# Or directly
uv run pytest -v

Project Structure

mcp-web-tools/
  src/
    mcp_web_tools/
      __init__.py       # Package metadata
      server.py         # MCP server implementation
      tools.py          # Tool implementations (search, fetch)
  tests/
    test_tools.py       # Unit tests
  pyproject.toml        # Project configuration
  Makefile              # Install/uninstall automation

Dependencies

• mcp - Model Context Protocol SDK

• ddgs - DuckDuckGo Search API

• httpx - Async HTTP client

• lxml - HTML parsing (optional; falls back to regex-based extraction if not installed)

License

MIT