ollama-websearch-mcp
This MCP server exposes Ollama's hosted web search and web fetch APIs as tools for any MCP client.
web_search: run a web search with a required
queryand optionalmax_results(default 10), returning search results.web_fetch: fetch a single absolute
url, returning page content and related metadata.MCP integration: use it from clients like Claude Desktop, Cursor, OpenCode, and MCPorter via stdio or HTTP.
Cloud-backed: requires an Ollama account/API key and sends queries/URLs to Ollama's cloud service, so avoid confidential data.
Provides tools for performing web searches and fetching web page content using Ollama's hosted search API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ollama-websearch-mcp search for latest AI research papers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ollama Search MCP Server
MCP server exposing Ollama's hosted web search and web fetch APIs as tools for any MCP client.
Overview
The server provides two tools:
web_search: search the web through Ollama's hosted search API
web_fetch: fetch a web page and return its content
It works with any MCP client, including Claude Desktop, Cursor, OpenCode, and MCPorter. An Ollama account and API key are required for the cloud endpoints.
Related MCP server: mcp-web-tools
Requirements
Python 3.10+
Ollama account (for cloud API access)
Installation
PyPI
uvx ollama-search-mcp
# or install the console script
pip install ollama-search-mcpuvx runs the server on demand, which is the recommended command for MCP client
configuration.
From Git
uvx --from git+https://github.com/akopper/ollama-search-mcp ollama-search-mcpPin a release with @<tag>:
uvx --from 'git+https://github.com/akopper/ollama-search-mcp@v0.2.1' ollama-search-mcpDocker
The Docker image defaults to HTTP mode.
# HTTP mode (default) - for remote usage
docker run -d -p 8000:8000 -e OLLAMA_API_KEY=your-api-key ghcr.io/akopper/ollama-search-mcp
# stdio mode - for Claude Desktop/Cursor
docker run -it --rm -e OLLAMA_API_KEY=your-api-key ghcr.io/akopper/ollama-search-mcp --stdioDocker Compose
cp .env.example .env
# Edit .env with your API key
docker-compose up -dFrom Source
git clone https://github.com/akopper/ollama-search-mcp.git
cd ollama-search-mcp
pip install -e .Configuration
Environment Variables
Variable | Description | Default |
| API key for Ollama cloud services | None |
| Host URL for Ollama |
|
Getting an API Key
Go to ollama.com
Sign in to your account
Navigate to API settings
Generate an API key
Search queries and fetched URLs are sent to Ollama's cloud service. Do not send confidential data in search queries.
Usage
Running the Server
stdio mode (default, for Claude Desktop/Cursor)
# Using the installed command
ollama-search-mcp
# Explicit stdio (same as the default)
ollama-search-mcp --stdio
# Or on demand with uvx
uvx ollama-search-mcp
# Or directly with Python
python -m ollama_search_mcp.serverHTTP mode (for remote usage)
python -m ollama_search_mcp.server --httpThe server starts on http://localhost:8000/mcp by default. Use --host and --port
to change the bind address, for example inside a container:
python -m ollama_search_mcp.server --http --host 0.0.0.0 --port 8000Claude Desktop Integration
Add the following to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"ollama-search": {
"command": "uvx",
"args": ["ollama-search-mcp"],
"env": {
"OLLAMA_API_KEY": "your-api-key-here"
}
}
}
}A globally installed ollama-search-mcp console script also works as command.
Cursor Integration
Add to Cursor settings (or .cursor/mcp.json in the project):
{
"mcpServers": {
"ollama-search": {
"command": "uvx",
"args": ["ollama-search-mcp"],
"env": {
"OLLAMA_API_KEY": "your-api-key-here"
}
}
}
}OpenCode Integration
Add the server to your ~/.config/opencode/opencode.jsonc:
{
"mcp": {
"servers": {
"ollama-search": {
"type": "local",
"command": ["uvx", "ollama-search-mcp"],
"environment": {
"OLLAMA_API_KEY": "{env:OLLAMA_API_KEY}"
}
}
}
}
}Then run opencode mcp list to verify the connection; it should report
✓ ollama-search connected.
If OpenCode is started from a desktop session instead of a login shell, it
usually does not inherit ~/.bashrc. Two things then break: ~/.local/bin is
missing from PATH (so uvx cannot be spawned) and exported variables like
OLLAMA_API_KEY are unset (so {env:OLLAMA_API_KEY} becomes an empty string).
In that case use an absolute command path and read the key from a file:
mkdir -p ~/.config/opencode/secrets
printf '%s' 'your-api-key-here' > ~/.config/opencode/secrets/ollama-search.key
chmod 600 ~/.config/opencode/secrets/ollama-search.key{
"mcp": {
"servers": {
"ollama-search": {
"type": "local",
"command": ["/home/you/.local/bin/uvx", "ollama-search-mcp"],
"environment": {
"OLLAMA_API_KEY": "{file:./secrets/ollama-search.key}"
}
}
}
}
}{file:…} paths are resolved relative to the config file, and ~/ is
expanded, so {file:~/.config/opencode/secrets/ollama-search.key} works as
well. Keep the file free of a trailing newline, otherwise it becomes part of
the header value. If your OpenCode version does not support {file:…} yet,
put the key into environment literally instead.
Symptom | Cause | Fix |
|
| use the absolute |
Tools work but |
| read it from a file as shown above, set it literally, or export it in the environment that starts OpenCode |
OpenCode Skill
The repository ships an OpenCode skill that teaches the agent how to call the
server's tools. It lives at .opencode/skills/ollamawebsearch/SKILL.md.
Install it globally so it is available in every OpenCode project:
mkdir -p ~/.config/opencode/skills/ollamawebsearch
cp .opencode/skills/ollamawebsearch/SKILL.md \
~/.config/opencode/skills/ollamawebsearch/SKILL.mdTo keep the installed skill in sync with this repository, link it instead:
mkdir -p ~/.config/opencode/skills
ln -s "$PWD/.opencode/skills/ollamawebsearch" \
~/.config/opencode/skills/ollamawebsearchFor a single project, copy the directory to
<project>/.opencode/skills/ollamawebsearch/. OpenCode also discovers skills
in ~/.claude/skills and ~/.agents/skills.
The skill is registered as ollamawebsearch; load it with @ollamawebsearch
or the skill tool. OpenCode reloads skills automatically, so no restart is
required. When working inside this repository, OpenCode already discovers the
skill from .opencode/skills.
MCPorter Integration
MCPorter can discover and use this server. Example config/mcporter.json:
{
"mcpServers": {
"ollama-search": {
"description": "Ollama web search and web fetch MCP server",
"command": "uvx",
"args": ["ollama-search-mcp"],
"env": {
"OLLAMA_API_KEY": "$env:OLLAMA_API_KEY"
}
}
}
}Or run ad-hoc:
# List tools
npx mcporter list ollama-search
# Call a tool
npx mcporter call ollama-search.web_search query:python max_results:10Available Tools
web_search
Search the web through Ollama's hosted search API.
Parameters:
query(required): the search querymax_results(optional): maximum number of results (default: 10)
Returns: a dictionary with a results list; each entry contains title, url, and
content.
web_fetch
Fetch a single web page.
Parameters:
url(required): the absolute URL to fetch
Returns: a dictionary containing the page title, content, and links.
Development
Setup
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Or with uv
uv sync --extra devRunning Tests
# Run all tests
pytest
# Run with coverage
pytest --cov --cov-report=term-missing
# Run a single test
pytest tests/test_server.py::TestWebSearch::test_web_search_returns_dictLinting and Formatting
ruff check src/ tests/
ruff format --check src/ tests/Building Distributions
python -m build
python -m twine check dist/*Running the Server for Development
# stdio mode with mcp dev
mcp dev src/ollama_search_mcp/server.py
# Or run directly
python -m ollama_search_mcp.serverReleasing
See RELEASING.md for versioning, tagging, and PyPI trusted publishing.
License
MIT. See LICENSE.
Available Tools
2 toolsweb_fetchA
Fetch the content of a web page.
Args: url: The absolute URL to fetch.
Returns: A dictionary containing the fetched content with html, text, and metadata.
Inputs: url (required). Returns: object
web_searchA
Perform a web search using Ollama's hosted search API.
Args: query: The search query to run. max_results: Maximum number of results to return (default: 10).
Returns: A dictionary containing search results with title, url, and snippet.
Inputs: query (required), max_results. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
Web search and web fetch are clearly distinct operations with no overlap. An agent can easily tell them apart based on their names and descriptions.
Both tools follow the same web_<verb> pattern, making the naming predictable and consistent. The convention is uniform across the entire set.
Only two tools are provided, which feels thin for a general-purpose websearch server. The count is borderline but acceptable for a narrow scope.
Search and fetch cover the core operations for a websearch tool. Minor gaps exist (e.g., no advanced filtering or content extraction options), but no critical dead ends are apparent.
Maintenance
Related MCP Connectors
Web data for agents. Extract web pages, crawl websites, discover URLs, and search the web.
Hosted browser for agents: open pages, search the web, extract data, read PDFs and take screenshots.
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Web search and page reading for AI agents, including JSON APIs, RSS feeds and YouTube.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables web content retrieval and semantic search capabilities through the Jina AI API. Provides tools to fetch content from URLs and perform intelligent web searches with natural language queries.3MIT
- AlicenseAqualityDmaintenanceProvides web access capabilities for LLMs including search, fetching, content extraction, PDF reading, image viewing, and screenshots.346MIT
- AlicenseNot gradedqualityFmaintenanceProvides web search and page fetching capabilities using Ollama's API.MIT
- AlicenseAqualityBmaintenanceEnables web search and web fetch operations using Ollama's hosted APIs, allowing MCP clients to search the web and retrieve page content.234 PyPIMIT