mcp -freesearch

This MCP server provides a FreeSearch service built on top of a SearXNG instance. It exposes a collection of specialized search tools that cover general web search, news, images, videos, maps, music, IT, science, files, and social media search, all without requiring API keys. The server is designed to be MCP-client friendly, returning results in HTML or JSON formats depending on the client request. Available tools include free_general_search, free_news_search, free_image_search, free_video_search, free_map_search, free_music_search, free_it_search, free_science_search, free_file_search and free_social_media_search. Each tool accepts common parameters such as query, language, safe_search, time_range and output_format to tailor results. It is configured to work with a SearXNG instance and can be run via uvx or directly from source with Python.

To use via Claude Desktop or MCP Inspector, point the MCP server configuration at the appropriate command and ensure the environment variable SEARXNG_API_URL is set to your SearXNG endpoint. For example, the free-search server entry maps to running uvx mcp-server-freesearch with SEARXNG_API_URL set, or running python main.py when using the source distribution.

Prerequisites:

• Python 3.10 or newer
• MCP compatible client and an accessible SearXNG instance
• uvx tooling (for the recommended installation method)

Option A: Install via uvx (recommended)

1. Install the MCP server package via uvx: uvx mcp-server-freesearch
2. Ensure Python is available and the SEARXNG_API_URL environment variable is set when running the server: export SEARXNG_API_URL="https://searx.bndkt.io"

Option B: Install from source

1. Clone the repository: git clone <repository-url> cd mcp-server-freesearch
2. Create and activate a virtual environment: uv venv source .venv/bin/activate # Windows: .venv\Scripts\activate
3. Install the package in editable mode: uv pip install -e .

Running the server (examples):

• Via uvx (recommended): uvx mcp-server-freesearch
• From source: python main.py

Development and testing helpers:

• MCP Inspector usage example: npx @modelcontextprotocol/inspector python main.py

Tips and troubleshooting:

• Ensure SEARXNG_API_URL points to a reachable SearXNG instance; network issues will cause search failures.
• If using JSON output, configure the SearXNG instance to support json formats as needed (via searxng settings).
• Environment variables: besides SEARXNG_API_URL, you may set optional SEARXNG_COOKIE, SEARXNG_USER_AGENT, SEARXNG_REQUEST_TIMEOUT and ENV_FASTMCP_LOG_LEVEL to optimize behavior and logging.
• If you run via Claude Desktop, you can specify the config with either uvx or python as shown in the README; adjust paths and environment as appropriate for your platform.
• Common errors include JSON parsing errors from the SearXNG response or rate limits; check the SearXNG instance status and response formats, and verify the output_format parameter (html/json).
• For containerized deployments, ensure the SearXNG container is reachable from the MCP server and that the exposed port is accessible.