README.md•6.01 kB
# MCP Server
Give your AI assistants the power to help you more effectively. This server lets them safely access
websites and search the web - with clear feedback about what's happening and helpful error messages
when things go wrong.
- [🛠️ What tools does this server offer?](#️-what-tools-does-this-server-offer)
- [🏎️ How can I run it?](#️-how-can-i-run-it)
- [🐋 Using Docker (recommended)](#-using-docker-recommended)
- [💻 Running locally](#-running-locally)
- [🔌 How to connect](#-how-to-connect)
- [📚 Learn more about MCP](#-learn-more-about-mcp)
- [📄 License](#-license)
## 🛠️ What tools does this server offer?
The server provides two powerful tools that help AI assistants solve real-world problems:
| Tool | What it can do |
| ------------------ | --------------------------------------------------------------------------- |
| [Search](docs/search.md) | Search the web via SearXNG for current information, specific resources, or to perform calculations. |
| [Web](docs/web.md) | Access websites and process their content. Can convert pages to markdown for easy reading, get the raw content, or extract links. |
## 🏎️ How can I run it?
### 🐋 Using Docker (recommended)
The server runs in Docker containers to keep things safe and simple. Here's how to get started:
1. [Install Docker](https://docs.docker.com/engine/install/) if you haven't already
2. Create a file called `docker-compose.yml` with:
```yaml:docker-compose.yml
services:
mcp-server:
environment:
# Required: URL for your SearXNG instance's Search API
- SEARXNG_QUERY_URL=http://searxng:8080
# Optional: Configure network mode (SSE) for LibreChat etc.
- SSE_HOST=0.0.0.0
- SSE_PORT=8080
# Optional: Set a custom User-Agent for web requests
- USER_AGENT=MCP-Server/1.0 (github.com/tcpipuk/mcp-server)
image: ghcr.io/tcpipuk/mcp-server/server:latest
ports: # Only needed if using SSE_HOST/SSE_PORT
- "8080:8080" # Expose port 8080 on host
restart: unless-stopped
stop_grace_period: 1s
# Example SearXNG service (optional, adapt as needed)
# searxng:
# environment:
# - SEARXNG_BASE_URL=http://searxng:8080 # Ensure SearXNG knows its own URL
# image: searxng/searxng:latest
# restart: unless-stopped
# volumes:
# - ./searxng:/etc/searxng:rw
```
> **Important**: You *must* provide the `SEARXNG_QUERY_URL` environment variable, pointing to
> the Search API endpoint of your SearXNG instance (usually ending in `/` or `/search`).
>
> Setting `SSE_HOST` and `SSE_PORT` enables network mode (Server-Sent Events), recommended for
> multi-container setups like LibreChat. If omitted, the server uses standard I/O.
3. Run `docker compose up -d` to start the server container (and optionally SearXNG).
Most people use this with either:
- [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) - connects directly via stdio
(omit `SSE_HOST`/`SSE_PORT` in `docker-compose.yml`).
- [LibreChat](https://www.librechat.ai/docs/local) - connects over the network via SSE.
For LibreChat, add this to your `librechat.yaml` (assuming `SSE_PORT=8080`):
```yaml:librechat.yaml
mcpServers:
mcp-server:
iconPath: "/path/to/icon.png" # Optional: Custom icon
label: "MCP Web/Search" # Optional: Custom label shown in UI
type: sse
url: http://mcp-server:8080/sse # Adjust host/port if needed
```
### 💻 Running locally
1. Install `uv` (requires Python 3.13+):
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
> **Note:** If you already have `uv` installed, update it with `uv self update`.
2. Create and activate a virtual environment:
```bash
uv venv
source .venv/bin/activate # Linux/macOS
# or
.venv\Scripts\activate # Windows
```
3. Install dependencies from the lockfile:
```bash
uv sync
```
4. Set required environment variables:
```bash
# Required: URL for your SearXNG instance's Search API
export SEARXNG_QUERY_URL="http://your-searxng-instance.local:8080"
# Optional: Custom User-Agent
export USER_AGENT="CustomAgent/1.0"
```
5. Run the server:
```bash
# For network (SSE) mode (e.g., for LibreChat)
mcp-server --sse-host 0.0.0.0 --sse-port 3001
# For direct stdio mode (e.g., for Claude Desktop)
mcp-server
```
Available arguments:
- `--sse-host`: SSE listening address (e.g., `0.0.0.0`). Enables SSE mode.
- `--sse-port`: SSE listening port (e.g., `3001`). Enables SSE mode.
- `--user-agent`: Custom User-Agent string (overrides `USER_AGENT` env var).
> **Note**: If neither `--sse-host` nor `--sse-port` are provided (and `SSE_HOST`/`SSE_PORT` env
> vars are not set), the server defaults to `stdio` mode. The `SEARXNG_QUERY_URL` environment
> variable is *always* required.
## 🔌 How to connect
You can connect to the server in two ways:
| Method | What it means | When to use it |
| ------------------------- | ------------------------------------------------------- | ----------------------------------------------- |
| Network connection (SSE) | The server listens on a network port for connections. | Best for LibreChat or other networked clients. |
| Direct connection (stdio) | The server communicates directly via standard input/out. | Useful for local testing or Claude Desktop. |
## 📚 Learn more about MCP
Here are a few resources to get you started:
- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [MCP Example Servers](https://github.com/modelcontextprotocol/servers)
## 📄 License
This project is licensed under the GPLv3. See the [LICENSE](LICENSE) file for full details.