Open Agent Search README

Open Agent Search

One self-hostable search and content layer for AI agents and applications.

What is OAS? · Agent setup · Capabilities · Architecture · API surface · Contributing

Set up with your agent

Copy this prompt into your coding agent:

Set up Open Agent Search for this project using
https://github.com/Jayanth-MKV/open-agent-search. Read its README and
skills/open-agent-search-setup/SKILL.md. Reuse uv if installed, otherwise
install it using the official uv instructions for my OS. Configure the
local stdio MCP server with the pinned package and managed Python version
from the repository's MCP manifest. Merge the server into this agent's
configuration without replacing existing servers. Install the
open-agent-search-setup and open-agent-search skills for this agent in
project scope. Verify the MCP connection and available tools, then try
one web search. Tell me if a client restart is needed. No API key is required.

Installation commands

With Node.js 22+ and uv installed:

npx --yes open-agent-search@1.0.5 --version
npx --yes open-agent-search@1.0.5 mcp
# Or start the HTTP API:
npx --yes open-agent-search@1.0.5 serve

The npm launcher uses the pinned Python core. It requires uv on PATH; uv manages Python 3.12 and dependencies.

With uv installed, run the MCP server in an isolated environment:

uvx --python 3.12 --from open-agent-search==1.0.5 oas-mcp

uv can download Python 3.12 when it is missing. The first run downloads dependencies; the client starts and stops this stdio process after configuration.

For a persistent PyPI installation and HTTP server:

uv tool install --python 3.12 open-agent-search==1.0.5
open-agent-search

The HTTP server listens on port 8000 on all interfaces. Use stdio for an agent that only needs local tools.

Install both skills for Codex in the current project:

npx --yes skills add Jayanth-MKV/open-agent-search --skill open-agent-search-setup open-agent-search --agent codex --copy --yes

Replace codex with claude-code, cursor, opencode, or your supported agent. Add --global only for installation across projects. Plugin and manual setup. Use either npm or PyPI above; both start the same Python implementation.

In Claude Code 2.1.275+, install both skills and the MCP configuration in one step:

/plugin install open-agent-search --marketplace Jayanth-MKV/open-agent-search --scope project

What is Open Agent Search?

Open Agent Search (OAS) is an independent retrieval layer for AI agents and applications. It provides one consistent search and content surface across local and deployed integrations.

OAS replaces separate adapters for every search vertical with one consistent tool surface. Run it locally for a single coding agent or deploy the HTTP service for shared agent and application workloads.

Search sources, transports, and client integrations can evolve without changing the repository's core goal: give agents and applications a dependable retrieval boundary they can control.

Connect MCP or HTTP

Add search to Claude Code

claude mcp add oas -- uvx --python 3.12 --from open-agent-search==1.0.5 oas-mcp

Restart Claude Code, then ask it to search the web, news, images, videos, or books. The same uvx command works with Cursor, VS Code, Windsurf, OpenClaw, and other MCP clients.

{
  "mcpServers": {
    "open-agent-search": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "open-agent-search==1.0.5", "oas-mcp"]
    }
  }
}

Run the HTTP API

uv tool install --python 3.12 open-agent-search==1.0.5
open-agent-search

Make a first search:

curl "http://localhost:8000/api/search/text?q=python+programming&max_results=5"

The server exposes REST endpoints at http://localhost:8000, interactive API docs at /docs, and streamable HTTP MCP at /ai/mcp.

Capabilities

• One search layer, multiple transports. Use stdio MCP locally or serve REST and MCP over HTTP.
• No provider API key required. Search is powered by the ddgs library.
• Self-hostable. Run locally, in Docker, or deploy the HTTP service to Vercel.
• Framework-independent. The protocol surface works across major MCP clients and agent stacks.
• Production-minded defaults. Typed FastAPI routes, rate limiting, health checks, tests, and deployment guides are included.

Architecture

The local MCP command and the HTTP service share the same search and content capabilities. Choose the connection path that matches where the consuming agent or application runs.

Two deployment paths

Search surface

See the API reference and MCP tool reference for parameters and response shapes.

Privacy model

OAS does not require an OAS account or a search-provider API key, and it can run on infrastructure you control. Search queries still have to reach upstream search providers through DDGS, so this project should not be treated as an anonymity network. Review your deployment logs, network policy, and upstream-provider terms for sensitive workloads.

Install and deploy

From source

git clone https://github.com/jayanth-mkv/open-agent-search.git
cd open-agent-search
uv sync
uv run open-agent-search

Docker

docker compose up -d

Deployment details: Docker · Vercel

Documentation

• Installation
• Quick start
• MCP integrations
• API endpoints
• Contributing

Registries and agent discovery

• Packages: npm and PyPI.
• Local MCP bundle: Smithery. It runs on your machine and requires Node.js 22+ and uv.
• MCP Registry namespace: io.github.jayanth-mkv/open-agent-search. The release workflow publishes server.json after both packages are available. Check the registry record.
• Agent skills: Open Agent Search and setup are published on ClawHub. You can also install them from GitHub using the commands above. The skills.sh directory discovers skills through real installations; a repository alone does not guarantee a listing.
• Glama: glama.json declares the GitHub maintainer. Directory submission and ownership verification require a separate Glama sign-in.

The npm path requires Node.js 22+ and uv. The PyPI path uses uv to manage Python 3.12. This project provides a local server and deployment code; it does not provide a shared hosted search endpoint.

The local MCPB bundle is built with python scripts/build_mcpb.py. It contains the pinned npm launcher and requires Node.js 22+ and uv on PATH. Its first launch downloads the Python core and dependencies. No credentials are bundled.

ClawHub distributes its skill copies under MIT-0, as required by that registry. This repository and its packages remain MIT licensed. GitHub Actions previews skill changes on pushes to main and publishes them on releases when CLAWHUB_TOKEN and the repository variable PUBLISH_CLAWHUB=true are configured. The workflow checks that the authenticated ClawHub owner matches the source repository owner.

Development

uv sync --group dev
uv run pytest
uv run ruff check .

Open Agent Search is currently beta software. Bug reports and focused pull requests are welcome; see CONTRIBUTING.md.

License

MIT

Maintained by Xplormity Collective.