# Ollama Web Search MCP Server

An [MCP](https://modelcontextprotocol.io) server that exposes [Ollama's web search API](https://ollama.com) as a `web_search` tool for Claude Code.

Use it when the built-in Claude Code `WebSearch` returns no results for a site — the Ollama search backend indexes sites (like small personal blogs) that other backends miss.

## Features

- Single `web_search` tool: `query` (required) + `count` (optional, 1–10, default 5)
- Reads your API key from the environment — never hardcoded, never committed
- 10s outbound timeout, friendly errors for missing key / bad status / network failure
- Pure Node.js stdio server — no build step, no runtime outside Node 18+

## Prerequisites

- [Node.js](https://nodejs.org) 18+ (tested on 20.x)
- An [Ollama](https://ollama.com) account with an **API key** (Settings → API Keys)

## Install

```bash
git clone https://github.com/wzul/ollama-web-search-mcp.git
cd ollama-web-search-mcp
npm install
```

## Register with Claude Code

Register the server globally (available in every project) with one command:

```bash
claude mcp add --scope user ollama-web-search -- node "$HOME/ollama-web-search-mcp/index.js"
```

> **Why `--scope user`:** `claude mcp add` defaults to the project-local scope. Without this flag the server is registered to the current project only and silently won't load when Claude Code is started from any other directory. If `web_search` doesn't appear after a restart, the registration is almost certainly project-scoped — fix it with `claude mcp add --scope user ...` (then `cd <repo> && claude mcp remove ollama-web-search -s local` to drop the stale entry).

Or add it manually to the top-level `mcpServers` object in `~/.claude.json`:

```json
{
  "mcpServers": {
    "ollama-web-search": {
      "command": "node",
      "args": ["/absolute/path/to/ollama-web-search-mcp/index.js"]
    }
  }
}
```

## Set your API key

The server reads the key from the environment, so export it in your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):

```bash
export OLLAMA_API_KEY="your-ollama-api-key"
```

> **Security:** use a key you have not shared anywhere. If a key was ever pasted into a chat, log, or screenshot, rotate it at [ollama.com/settings/keys](https://ollama.com/settings/keys) before using it here.

Then **restart Claude Code** — the `web_search` tool will be available in every session.

## (Optional) Disable the built-in WebSearch

Claude Code ships a built-in `WebSearch` tool. If you want your sessions to use *only* the Ollama-backed `web_search`, deny the built-in one in `~/.claude/settings.json`:

```json
{
  "permissions": {
    "deny": ["WebSearch"]
  }
}
```

`deny` takes precedence over `allow`, and rules merge across scopes, so this stays blocked even if another settings file allows it. Restart Claude Code afterwards. You can verify with `/permissions` that `WebSearch` is no longer offered.

## Usage

Ask Claude Code to search, e.g.:

```
web_search "wanzul.net"
web_search "best 5G plan malaysia" count 10
```

Results come back as a numbered list: **title**, **URL**, and **content snippet**.

## Test

```bash
npm test
```

Runs 10 tests: unit tests for the fetch wrapper and result formatting (mocked fetch) plus a live stdio smoke test that drives the MCP protocol.

## Helper skill (optional)

The repo ships a copy-paste install skill at `.claude/skills/install-ollama-web-search/`. Install it so you (or Claude Code) can reproduce these steps on demand:

```bash
mkdir -p ~/.claude/skills
cp -r .claude/skills/install-ollama-web-search ~/.claude/skills/
```

Once installed, an agent can follow it (or ask "install ollama-web-search") instead of retyping commands from memory.

## Layout

- `index.js` — MCP stdio server + `searchOllama` / `formatResults` exports
- `test.js` — unit tests (mocked fetch) + stdio smoke test
- `package.json` — deps (`@modelcontextprotocol/sdk`) and scripts

## License

MIT