OpenReview Python Server

MCP server that helps LLMs write correct openreview-py code. Two knowledge layers: live introspection of the installed library (method signatures, docstrings, class structures) and static knowledge (best practices, code examples, workflow guides).

Tools

Tool	Purpose
search_api	Search OpenReview API methods by topic (results tagged [v1]/[v2])
get_method_signature	Get detailed method signatures and docstrings
get_best_practices	Concepts, conventions, and anti-patterns from best_practices.md (curated in this repo)
search_test_examples	Real call sites from the upstream openreview-py/tests/ directory (auto-indexed)

Usage

Quick start (recommended)

Clone, build, and run as a long-running local HTTP service. The default image is lean — search_test_examples reads the upstream openreview-py/tests/ directory from a bind-mount, so point -v at your local checkout (every openreview-py developer has one):

git clone https://github.com/openreview/openreview-mcp.git
cd openreview-mcp
docker build -t openreview-mcp .

# Adjust the path to your local openreview-py checkout
docker run -d --name openreview-mcp -p 8080:8080 \
  -v /path/to/your/openreview-py:/openreview-py \
  openreview-mcp --transport streamable-http

No env var needed — the image already sets OPENREVIEW_KNOWLEDGE_PATH=/openreview-py. Drop the -v flag if you don't need search_test_examples; the other three tools (search_api, get_method_signature, get_best_practices) work without any mount, and the tests-index tool returns a clear "disabled" message.

Add to .mcp.json (project-level) or to ~/.claude.json under the relevant project's mcpServers:

{
  "mcpServers": {
    "openreview": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Restart Claude Code (/exit and relaunch). All 4 tools become available; search_test_examples indexes the bind-mounted openreview-py/tests/ directory at container start.

To stop the server:

docker stop openreview-mcp && docker rm openreview-mcp

To upgrade later (picks up new openreview-mcp code and new upstream openreview-py for the introspection layer):

git pull && docker build --no-cache -t openreview-mcp .
docker stop openreview-mcp && docker rm openreview-mcp
docker run -d --name openreview-mcp -p 8080:8080 \
  -v /path/to/your/openreview-py:/openreview-py \
  openreview-mcp --transport streamable-http

--no-cache forces pip to refetch the latest openreview-py for introspection. The tests-index comes from your bind-mount, so git pull in /path/to/your/openreview-py is what refreshes that layer — no image rebuild needed for upstream-test changes.

Build a self-contained image (Cloud Run / VM deployments)

When the host filesystem won't be available — e.g., shipping to Cloud Run, a managed VM, or a teammate without an openreview-py clone — opt in to baking a shallow upstream clone into the image:

docker build --build-arg CLONE_OPENREVIEW_PY=true -t openreview-mcp:full .

docker run -d --name openreview-mcp -p 8080:8080 \
  openreview-mcp:full --transport streamable-http

Adds ~60 MB and an implicit dependency on GitHub at build time, but no -v needed at runtime. A runtime bind-mount at /openreview-py still works and transparently replaces the baked-in clone for live-edit workflows.

Alternative: stdio per-call (no long-running service)

If you'd rather Claude Code spawn a fresh container on every tool call (lower idle footprint, but introspection + index rebuild on each invocation):

{
  "mcpServers": {
    "openreview": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/openreview-py:/openreview-py",
        "openreview-mcp"
      ]
    }
  }
}

Remote server (public, optional)

Deploy the same image to any host that can run Docker (Cloud Run, Fly.io, a VM, etc.) and point clients at its public URL:

{
  "mcpServers": {
    "openreview": {
      "type": "http",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

No API token is needed — this server provides knowledge tools only (read-only, no live API access).

CLI options

openreview-mcp [--transport stdio|sse|streamable-http] [--port 8080] [--host 0.0.0.0]

Environment variables

Var	Purpose
OPENREVIEW_KNOWLEDGE_PATH	Directory hint for search_test_examples and (optionally) for an override best_practices.md. The Dockerfile sets this to /openreview-py by default — bind-mount your local checkout there, or use --build-arg CLONE_OPENREVIEW_PY=true to bake an upstream clone into the image. If the resolved directory contains a best_practices.md, that file is loaded instead of the bundled one (otherwise the bundled copy is used — no error). The tests/ subdir under this path is what search_test_examples indexes; if it doesn't exist, the tool returns a clear disabled message and the other three tools work unaffected.
OPENREVIEW_TESTS_PATH	Explicit override for the tests/ directory used by search_test_examples. Falls back to {OPENREVIEW_KNOWLEDGE_PATH}/tests/.

Reusable Registration

Other FastMCP servers can mount the knowledge tools without running the full server:

from openreview_mcp.registration import register_knowledge_tools

register_knowledge_tools(mcp)  # mounts 4 knowledge tools onto your FastMCP instance

Keeping Up with openreview-py

The server has three layers, each with a different freshness story:

• Introspection (search_api, get_method_signature) — reads the installed openreview-py at startup. Refreshes when you rebuild the image; --no-cache forces pip to refetch upstream main.
• Static knowledge (get_best_practices) — reads best_practices.md (concepts, conventions, anti-patterns; the rules tests assert but never explain). Curated and edited in this repo; bundled inside the image. Refresh by editing openreview_mcp/knowledge_files/best_practices.md and rebuilding.
• Test-suite index (search_test_examples) — AST-indexed at startup from the tests/ subdir of /openreview-py inside the container. Default workflow: bind-mount your local openreview-py checkout at /openreview-py; git pull in that checkout + restart the container refreshes the index. For self-contained builds (Cloud Run / VM), opt in with --build-arg CLONE_OPENREVIEW_PY=true and docker build --no-cache re-fetches upstream.

Development

git clone https://github.com/openreview/openreview-mcp.git
cd openreview-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest tests/ -v