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, 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

Related MCP server: searxng-mcp

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

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