Basic MCP Tools

A small, self-hosted MCP (Model Context Protocol) server that gives your LLM a few essential tools: private web search, web page fetching, current weather, and the current date/time. It ships with its own SearXNG instance via Docker Compose, so search stays local and doesn't require any API keys.

Tools

Quick start (Docker Compose)

Requires Docker with the Compose plugin.

git clone https://github.com/Tyguy047/Basic-MCP-Tools.git
cd Basic-MCP-Tools
docker compose up -d --build

This starts two containers:

• searxng — the search backend. It is only reachable from inside the Compose network (not published to your host).

• basic-mcp-tools — the MCP server, listening on port 8080 using the streamable HTTP transport.

The MCP endpoint is:

http://localhost:8080/mcp

Connect a client

Any MCP client that supports streamable HTTP will work. For example, with Claude Code:

claude mcp add --transport http basic-tools http://localhost:8080/mcp

Or in a JSON-based client config:

{
  "mcpServers": {
    "basic-tools": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Configuration

• Timezone — get_date/get_time use the container's timezone. Set TZ in docker-compose.yml (defaults to America/New_York).

• SearXNG — settings live in searxng/settings.yml. The one requirement for the search tool is that the json output format stays enabled. The container generates a random SEARXNG_SECRET on each start.

• Search backend location — the MCP server finds SearXNG through the SEARXNG_IP and SEARXNG_PORT environment variables (set in docker-compose.yml).

• Weather units — get_weather reports imperial units (°F, mph, in) by default. Set WEATHER_UNITS to metric in docker-compose.yml for °C, km/h, and mm.

Running without Docker

You can run the server directly if you point it at an existing SearXNG instance (one with the json format enabled):

pip install -r requirements.txt
export SEARXNG_IP=<searxng-host>
export SEARXNG_PORT=<searxng-port>
python main.py

The server listens on 0.0.0.0:8080. Python 3.14 is used in the Docker image; other recent versions should work too.

Project layout

main.py                 # FastMCP server; registers the tools
functions/
  searxng.py            # search — queries SearXNG's JSON API
  fetch.py              # fetch_page — httpx + BeautifulSoup text extraction
  date.py               # get_date
  time.py               # get_time
  weather.py            # get_weather — Open-Meteo geocoding + forecast
searxng/settings.yml    # SearXNG config (enables JSON output)
docker-compose.yml      # searxng + mcp-tools services
Dockerfile              # Python 3.14 slim image for the MCP server

Notes

• The server is unauthenticated and intended for local or trusted-network use. Don't expose port 8080 to the public internet as-is.

• Adding a new tool is two steps: write a function in functions/ (its docstring becomes the tool description) and register it in main.py with mcp.tool()(your_function).