Standalone MCP web search powered by OpenCode's free models, with source URLs and validated JSON results.

OpenCode Search MCP

English · 한국어

Give an MCP client a single websearch tool using the official OpenCode CLI and its built-in web search. The default model is opencode/glm-5.3-flash-free. No Codex installation or subscription is required.

Features

• Free-model checks: checks model availability, tool support, and all advertised prices before inference. No paid fallback.
• Source-backed results: requires an actual completed search and verifies that every returned URL appeared in its output.
• Structured responses: titles, URLs, summaries, publication dates, ranks, and consistent error envelopes.
• Isolated requests: temporary settings, credentials, sessions, and cache; search-only authorization and bounded subprocesses.
• Standalone package: its own dependencies, CLI entry point, tests, and JSON Schemas.

Free models and keyless search depend on OpenCode and its search backend. Availability and rate limits can change. This is not a promise of unlimited free searches. See constraints.

Quick start

Requires Python 3.11+, uv, and Git.

git clone https://github.com/hikaMaeng/opencodesearch.git
cd opencodesearch
uv sync --locked

Install the tested OpenCode CLI 1.19.3 locally, without a global npm installation:

uv run --frozen python scripts/install_opencode.py

The helper downloads the official platform package, checks npm SHA-512 integrity, and prints the executable path under .tools/. Set that path as OPENCODE_MCP_BIN in your MCP client configuration below. An existing compatible CLI on PATH also works. OpenCode Desktop and the CLI are separate installations.

Connect your MCP client

Merge this entry into the client's existing mcpServers object. Replace every C:/path/to/opencodesearch with your checkout's absolute path.

{
  "mcpServers": {
    "opencodesearch": {
      "command": "C:/path/to/opencodesearch/.venv/Scripts/python.exe",
      "args": ["-m", "opencodesearch"],
      "env": {
        "OPENCODE_MCP_BIN": "C:/path/to/opencodesearch/.tools/opencode-1.19.3/opencode.exe"
      }
    }
  }
}

On macOS/Linux, use .venv/bin/python and .tools/opencode-1.19.3/opencode. Use absolute executable paths for GUI clients. Set the client's tool timeout to 210 seconds or longer for the default server timeout of 180 seconds.

Client	Configuration
LM Studio / generic MCP	Windows JSON · uv JSON
Hermes Agent	YAML example · registration steps
Codex	TOML example

Install directly from GitHub

With a compatible OpenCode CLI already available, a client can launch the package without cloning:

{
  "mcpServers": {
    "opencodesearch": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/hikaMaeng/opencodesearch.git", "opencodesearch"],
      "env": {"OPENCODE_MCP_BIN": "/absolute/path/to/opencode"}
    }
  }
}

Use a Git commit suffix (.git@<commit>) to pin this form to a revision. The checkout workflow uses uv.lock for exact dependency resolution. This repository does not require a PyPI release.

Search

The server exposes one tool, websearch:

{"query": "Python asyncio official documentation", "max_results": 3}

Each result contains title, url, snippet, published_at (or null), and rank. Results are deduplicated, limited to 1–10 items, and wrapped in a versioned response with search queries and provider metadata. Snippets are model-written summaries grounded in search output. See the API contract.

For a live command-line check:

$env:OPENCODE_MCP_BIN='C:/path/to/opencodesearch/.tools/opencode-1.19.3/opencode.exe'
uv run --frozen python scripts/smoke.py 'Python asyncio official documentation' --max-results 3

uv run --frozen opencodesearch starts a stdio MCP server; it waits for client requests rather than presenting an interactive search prompt.

Configuration

Environment variable	Default	Purpose
OPENCODE_MCP_BIN	opencode	CLI executable path or PATH command
OPENCODE_MCP_MODEL	opencode/glm-5.3-flash-free	An active, tool-capable OpenCode model with zero advertised prices
OPENCODE_MCP_TIMEOUT_SECONDS	180	Total queue + model check + search timeout, 1–600 seconds
OPENCODE_MCP_MAX_CONCURRENCY	1	Concurrent requests per server, 1–8

Development

uv sync --locked
uv run --frozen pytest -q -W error
uv run --frozen python scripts/export_schemas.py
uv build

Offline tests use a fake CLI and do not consume provider quota. Live search and permission checks are separate scripts. Windows is locally verified; the CI matrix checks offline behavior on Windows and Ubuntu.

Documentation

Topic	Reference
Purpose	Overview
Input, output, and errors	API
Installation and clients	Usage
Free-tier and security boundaries	Constraints
Design and execution	Architecture · Internals
Verification	Testing

Built on the official MCP Python SDK and OpenCode CLI.