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