Kode-Rex/webcat
3.2
If you are the rightful owner of webcat and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Web Cat MCP is a Model Context Protocol server that enhances AI models with web search and content extraction capabilities.
WebCat MCP Server
Web search and content extraction for AI models via Model Context Protocol (MCP)
Quick Start
# Run WebCat with Docker (30 seconds to working demo)
docker run -p 8000:8000 tmfrisinger/webcat:latest
# Open demo client
open http://localhost:8000/demo
What is WebCat?
WebCat is an MCP (Model Context Protocol) server that provides AI models with:
- š Web Search - Serper API (premium) or DuckDuckGo (free)
- š Content Extraction - Clean markdown conversion with Trafilatura
- š SSE Streaming - Real-time results via Server-Sent Events
- šØ Demo UI - Interactive testing interface
Built with FastAPI and FastMCP for seamless AI integration.
Features
- ā No Authentication Required - Simple setup
- ā Automatic Fallback - Serper API ā DuckDuckGo if needed
- ā Smart Content Extraction - Trafilatura removes navigation/ads/chrome
- ā MCP Compliant - Works with Claude Desktop, LiteLLM, etc.
- ā Rate Limited - Configurable protection
- ā Docker Ready - One command deployment
- ā Parallel Processing - Fast concurrent scraping
Installation & Usage
Docker (Recommended)
# With Serper API (best results)
docker run -p 8000:8000 -e SERPER_API_KEY=your_key tmfrisinger/webcat:2.2.0
# Free tier (DuckDuckGo only)
docker run -p 8000:8000 tmfrisinger/webcat:2.2.0
# Custom configuration
docker run -p 9000:9000 \
-e PORT=9000 \
-e SERPER_API_KEY=your_key \
-e RATE_LIMIT_WINDOW=60 \
-e RATE_LIMIT_MAX_REQUESTS=10 \
tmfrisinger/webcat:2.2.0
Local Development
cd docker
python -m pip install -e ".[dev]"
# Start MCP server
python mcp_server.py
# Or start demo server with UI
python simple_demo.py
Available Endpoints
| Endpoint | Description |
|---|---|
http://localhost:8000/demo | šØ Interactive demo UI |
http://localhost:8000/health | š Health check |
http://localhost:8000/status | š Server status |
http://localhost:8000/mcp | š ļø MCP protocol endpoint |
http://localhost:8000/sse | š SSE streaming |
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
SERPER_API_KEY | (none) | Serper API key for premium search (optional) |
PORT | 8000 | Server port |
LOG_LEVEL | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
LOG_DIR | /tmp | Log file directory |
RATE_LIMIT_WINDOW | 60 | Rate limit window in seconds |
RATE_LIMIT_MAX_REQUESTS | 10 | Max requests per window |
Get a Serper API Key
- Visit serper.dev
- Sign up for free tier (2,500 searches/month)
- Copy your API key
- Pass to Docker:
-e SERPER_API_KEY=your_key
MCP Tools
WebCat exposes these tools via MCP:
| Tool | Description | Parameters |
|---|---|---|
search | Search web and extract content | query: str, max_results: int |
scrape_url | Scrape specific URL | url: str |
health_check | Check server health | (none) |
get_server_info | Get server capabilities | (none) |
Architecture
MCP Client (Claude, LiteLLM)
ā
FastMCP Server (SSE Transport)
ā
Search Decision
āā Serper API (premium) ā Content Scraper
āā DuckDuckGo (free) ā Content Scraper
ā
Trafilatura (markdown)
ā
Structured Response
Testing
cd docker
# Run all tests
python -m pytest tests/unit -v
# With coverage
python -m pytest tests/unit --cov=. --cov-report=term --cov-report=html
# CI-safe (no external dependencies)
python -m pytest -v -m "not integration"
Current test coverage: 70%+ across all modules
Development
# Install with dev dependencies
pip install -e ".[dev]"
# Format code
make format
# Lint code
make lint
# Run tests
make test
# Full CI check
make ci
Project Structure
docker/
āāā mcp_server.py # Main MCP server
āāā simple_demo.py # Demo server with UI
āāā clients/ # Serper & DuckDuckGo clients
āāā services/ # Content scraping & search
āāā tools/ # MCP tool implementations
āāā models/ # Pydantic data models
ā āāā domain/ # Domain entities
ā āāā responses/ # API responses
āāā endpoints/ # FastAPI endpoints
āāā tests/ # Comprehensive test suite
Search Quality Comparison
| Feature | Serper API | DuckDuckGo |
|---|---|---|
| Cost | Paid (free tier available) | Free |
| Quality | āāāāā Excellent | āāāā Good |
| Coverage | Comprehensive (Google-powered) | Standard |
| Speed | Fast | Fast |
| Rate Limits | 2,500/month (free tier) | None |
Limitations
- Text-focused: Optimized for article content, not multimedia
- Rate limits: Respects configured limits to prevent abuse
- No JavaScript: Cannot scrape dynamic JS-rendered content
- PDF support: Detection only, not full extraction
Contributing
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure
make cipasses - Submit a Pull Request
See for development guidelines and architecture standards.
License
MIT License - see file for details.
Links
- GitHub: github.com/Kode-Rex/webcat
- Docker Hub: hub.docker.com/r/tmfrisinger/webcat
- MCP Spec: modelcontextprotocol.io
- Serper API: serper.dev
Version 2.2.0 | Built with ā¤ļø using FastMCP, FastAPI, and Trafilatura