omniref

One MCP interface to search image and video references across many search engines, built for AI image and video generation agents (reference-to-video, style, character and motion conditioning).

Status: pre-alpha. Only a deterministic mock provider exists today. The tool schema is the part to review.

Run

Requires Python 3.12+ and uv.

uv sync
uv run omniref          # streamable HTTP on http://127.0.0.1:8000/mcp
HOST=0.0.0.0 PORT=9000 uv run omniref

The server has no authentication. It binds to localhost by default; put it behind an authenticating proxy before exposing it.

Connect a client:

claude mcp add --transport http omniref http://127.0.0.1:8000/mcp

Related MCP server: multi-api-web-search

Tools

Layout

src/omniref/
  models.py        Reference, SearchRequest, SearchResponse (the unified schema)
  registry.py      Parallel fan-out, timeouts, error isolation, merge/dedupe
  server.py        FastMCP server and HTTP entrypoint
  providers/
    base.py        ReferenceProvider interface
    mock.py        Fake data for dev and tests
skills/
  omniref/SKILL.md   Agent skill that teaches the workflow
tests/

Adding a provider

Subclass ReferenceProvider, set name, description, media_types, implement async search(request) -> list[Reference], and register it in server.default_registry(). Map the native payload into Reference; raise on failure and the registry reports it in errors without affecting other providers.

Develop

uv run pytest
uv run ruff check . && uv run ruff format --check .

License

MIT. See LICENSE.