# Basic MCP Tools

A small, self-hosted [MCP](https://modelcontextprotocol.io) (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](https://github.com/searxng/searxng) instance via Docker Compose, so search stays local and doesn't require any API keys.

## Tools

| Tool | Description |
| --- | --- |
| `search` | Search the web through the bundled SearXNG instance. Returns titles, URLs, and snippets. |
| `fetch_page` | Fetch a URL and return its cleaned, readable text (scripts, nav, footers, etc. stripped out). |
| `get_date` | Get the current date (`YYYY-MM-DD`). |
| `get_time` | Get the current local time with timezone. |
| `get_weather` | Get the current weather for a town or city via [Open-Meteo](https://open-meteo.com) (no API key needed). |

## Quick start (Docker Compose)

Requires Docker with the Compose plugin.

```sh
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:

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

Or in a JSON-based client config:

```json
{
  "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):

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