Content
# 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, 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. |
## 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`).
## 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
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)`.
