4get

You run a lightweight MCP server that exposes the 4get Meta Search engine API to LLM clients via FastMCP. It provides multi-source search across web, images, and news with caching, retry logic, and rich responses, all configurable through environment variables and MCP client configurations.

How to use

Start by running the MCP server in your environment using your preferred tool (UV or Mise). Once running, you can connect MCP clients (such as IDE plugins or AI assistants) to perform web, image, and news searches. The server handles request caching, retries on transient failures, and returns structured results that include web results, featured answers, related searches, and pagination support.

How to install

Prerequisites you need on your machine are Python 3.13 or newer and a runtime to manage the server process (UV is recommended for dependency management). Ensure your environment can reach the 4get service base URL if you plan to use a remote instance.

uv sync

uv run -m mcp_4get

# Or, with Mise for orchestration
mise run

Configuration and running in production

Configure the server with environment variables to suit your deployment. The public instance defaults are sensible, but you can tailor base URL, caching, timeouts, and retry settings.

# Example production configuration
export FOURGET_BASE_URL="https://my-4get-instance.com"
export FOURGET_PASS="my-secret-token"        # optional for rate-limited setups
export FOURGET_CACHE_TTL="300"                 # seconds
export FOURGET_MAX_RETRIES="5"                 # retry attempts

uv run -m mcp_4get

MCP server integration for IDEs and assistants

You can integrate the 4get MCP server with popular IDEs and AI assistants using explicit MCP configurations. Below are examples you can copy into your integration tool’s MCP settings.

# Cursor IDE integration (stdio)
{
  "mcpServers": {
    "cursor": {
      "command": "uvx",
      "args": [
        "mcp_4get@latest"
      ],
      "env": {
        "FOURGET_BASE_URL": "https://4get.ca"
      }
    }
  }
}

# OpenAI Codex integration (stdio)
[mcp_servers.4get]
command = "uvx"
args = ["mcp_4get@latest"]
env = { FOURGET_BASE_URL = "https://4get.ca" }

Tools and endpoints

The server exposes three search tools that return richly formatted results and support pagination. You can choose from web, image, and news search tools. Each tool accepts an engine shorthand to pick the underlying scraper.

fourget_web_search(query: str, page_token: str = None, extended_search: bool = False, engine: str = None, extra_params: dict = None)

fourget_image_search(query: str, page_token: str = None, engine: str = None, extra_params: dict = None)

fourget_news_search(query: str, page_token: str = None, engine: str = None, extra_params: dict = None)

Engine shorthands and pagination

You can pass shorthand engine values to select a specific scraper. If you need to pass extra 4get parameters such as country or language, include them in extra_params.

ddg, brave, yandex, google, google_cse, mo jeek, qwant, startpage, etc. as engine values

Error handling and resilience

The server includes automatic retries with exponential backoff on rate limits and transient network errors. Non-retryable errors (like 404/500) fail fast with clear error types to help you diagnose issues.

Response format

Responses mirror the 4get API structure and include status, web results, featured answers, spelling corrections, related searches, and a pagination token when more results are available.

Using the async client directly

If you want to use the bundled async client outside MCP, you can access the same search capabilities directly from Python code.

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())

Security and best practices

Keep authentication tokens secret and rotate them as needed. When running in production, use a controlled network environment and apply proper access controls to the MCP endpoints.

Troubleshooting

If you encounter issues starting the server, verify your environment variables are set, ensure the base URL is reachable, and check the logs for any validation errors during startup.

Available tools

fourget_web_search

Performs a web search and returns results, featured answer, spelling, related queries, and a next page token for pagination.

fourget_image_search

Performs an image search and returns image results with pagination support.

fourget_news_search

Performs a news search and returns news results with pagination support.