MCP 4get

🚀 4get MCP Server

A MCP server that enables seamless access to the 4get Meta Search engine API for LLM clients via FastMCP.

✨ Features

• 🔍 Multi Search Functions: Conduct web, image, and news searches with comprehensive result formatting.
• ⚡ Smart Caching: Implement TTL-based response caching with configurable size limits.
• 🔄 Retry Logic: Apply exponential backoff for rate-limited and network errors.
• 🏗️ Production Ready: Utilize connection pooling, comprehensive error handling, and validation.
• 📊 Rich Responses: Receive featured answers, related searches, pagination support, and more.
• 🧪 Well Tested: Benefit from an extensive test suite including integration tests with real API, unit tests, and more.
• ⚙️ Highly Configurable: Fine-tune the server using 11+ environment variables.
• 🎯 Engine Shorthands: Select a 4get scraper via the engine parameter without memorizing query strings.

📦 Installation

📋 Requirements

• Python 3.13+
• uv for dependency management

🚀 Quick Start

# Install dependencies
uv sync

# Run the server
uv run -m mcp_4get

# Or use mise
mise run

⚙️ Configuration

The server can be highly configured through environment variables. All settings have reasonable defaults for the public https://4get.ca instance.

Core Settings

Caching & Performance

Retry & Resilience

💻 Usage Examples

Running the Server

Local Development

uv run -m mcp_4get

Production Deployment

# With custom configuration
export FOURGET_BASE_URL="https://my-4get-instance.com"
export FOURGET_PASS="my-secret-token"
export FOURGET_CACHE_TTL="300"
export FOURGET_MAX_RETRIES="5"

uv run -m mcp_4get

MCP Server Integration

Cursor IDE

Add this to your Cursor MCP configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "4get": {
      "command": "uvx",
      "args": [
        "mcp_4get@latest"
      ],
      "env": {
        "FOURGET_BASE_URL": "https://4get.ca"
      }
    }
  }
}

OpenAI Codex

Add this to your Codex MCP configuration (~/.codex/config.toml):

[mcp_servers.4get]
command = "uvx"
args = ["mcp_4get@latest"]
env = { FOURGET_BASE_URL = "https://4get.ca" }

Note: Replace /path/to/your/mcp-4get with the actual path to your project directory.

MCP Tools

fourget_web_search

fourget_web_search(
    query: str,
    page_token: str = None,        # Use 'npt' from previous response
    extended_search: bool = False, # Enable extended search mode
    engine: str = None,             # Pick a scraper from the supported engine list
    extra_params: dict = None      # Language, region, etc.
)

Response includes: web[], answer[], spelling, related[], npt

fourget_image_search

fourget_image_search(
    query: str,
    page_token: str = None,   # Use 'npt' from previous response
    engine: str = None,       # Pick a scraper from the supported engine list
    extra_params: dict = None # Size, color, type filters
)

Response includes: image[], npt

fourget_news_search

fourget_news_search(
    query: str,
    page_token: str = None,   # Use 'npt' from previous response
    engine: str = None,       # Pick a scraper from the supported engine list
    extra_params: dict = None # Date range, source filters
)

Response includes: news[], npt

Engine shorthands

All MCP tools accept an optional engine argument that maps directly to the 4get scraper query parameter. This shorthand overrides any scraper value you may include in extra_params.

If you need to pass additional 4get query parameters (such as country or language), continue to supply them through extra_params.

📄 Pagination

All tools support pagination via the npt (next page token):

# Get first page
result = await client.web_search("python programming")

# Get next page if available
if result.get('npt'):
    next_page = await client.web_search("ignored", page_token=result['npt'])

🐍 Using the Async Client Directly

import asyncio
from mcp_4get.client import FourGetClient
from mcp_4get.config import Config

async def main() -> None:
    client = FourGetClient(Config.from_env())
    data = await client.web_search(
        "model context protocol",
        options={"scraper": "mullvad_brave"},
    )
    for result in data.get("web", []):
        print(result["title"], "->", result["url"])

asyncio.run(main())

This enables you to integrate 4get search capabilities directly into your Python applications without going through the MCP protocol.

🔧 Technical Details

🛡️ Error Handling & Resilience

Automatic Retry Logic

• Rate Limiting (429): Exponential backoff with jitter
• Network Errors: Connection failures and timeouts
• Non-retryable: HTTP 404/500 errors fail immediately

Error Types

• FourGetAuthError: Rate limited or invalid authentication
• FourGetAPIError: API returned non-success status
• FourGetTransportError: Network or HTTP protocol errors
• FourGetError: Generic client errors

Configuration Validation

All settings are validated on startup, with clear error messages for misconfigurations.

📊 Response Format

Based on the real 4get API, responses include rich metadata:

{
  "status": "ok",
  "web": [
    {
      "title": "Example Result",
      "description": "Result description...",
      "url": "https://example.com",
      "date": 1640995200,
      "type": "web"
    }
  ],
  "answer": [
    {
      "title": "Featured Answer",
      "description": [{"type": "text", "value": "Answer content..."}],
      "url": "https://source.com",
      "table": {"Key": "Value"}
    }
  ],
  "spelling": {
    "type": "no_correction",
    "correction": null
  },
  "related": ["related search", "terms"],
  "npt": "pagination_token_here"
}

🧪 Testing

# Run all tests
uv run pytest

# Run only fast unit tests (exclude integration)
uv run pytest -m "not integration"

# Run integration tests with real 4get API
uv run pytest -m integration

# Run with coverage
uv run pytest --cov=src

# Run specific test categories
uv run pytest tests/test_cache.py      # Cache behavior tests
uv run pytest tests/test_client.py     # Client and retry logic tests
uv run pytest tests/test_integration.py # Real API integration tests

Test Categories

• Unit Tests: Fast, deterministic tests using mock transports
• Integration Tests: Real API tests with rate limiting and resilience validation
• Cache Tests: TTL expiration, eviction policies, concurrent access
• Retry Tests: Exponential backoff, error handling, timeout scenarios
• Configuration Tests: Validation logic and environment variable parsing

The tests follow FastMCP testing guidelines with comprehensive fixtures and proper isolation.

🤝 Contributing

1. Setup: Refer to the Installation and Quick Start sections.
2. Tests: See the Testing section.
3. Linting: Run uv run ruff check.
4. Format: Run uv run ruff format.

📄 License

GPLv3 License - see LICENSE file for details.