elog-mcp

OpenAPI/MCP server giving LLM agents read-only access to ELOG electronic logbooks over HTTP. Reference deployment: the T2K/ND280 elog at https://elog.nd280.org/elog/; works with any standard elogd instance.

• Search entries by full text (regex), attributes, and date range

• Read entries in full (attributes + body + attachments)

• Download attachments, discover logbooks

Strictly read-only: only HTTP GET requests are issued. TLS verification is on by default. Credentials come from the environment only and are never logged or echoed.

Setup

Requires Python ≥ 3.10 and uv:

uv sync

Related MCP server: mcp-opensearch

Configuration

All settings are environment variables (ELOG_ prefix):

Common prefix for every deployment:

export ELOG_URL=https://elog.nd280.org/elog
export ELOG_USER=your-shared-user
export ELOG_PASSWORD=your-shared-password

Deployment

ELOG_MCP_TRANSPORT picks how clients talk to the server:

stdio (local MCP clients)

uv run elog-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "elog": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/elog-mcp", "run", "elog-mcp"],
      "env": { "ELOG_URL": "…", "ELOG_USER": "…", "ELOG_PASSWORD": "…" }
    }
  }
}

opencode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "elog": {
      "type": "local",
      "command": ["uv", "--directory", "/absolute/path/to/elog-mcp", "run", "elog-mcp"],
      "environment": { "ELOG_URL": "…", "ELOG_USER": "…", "ELOG_PASSWORD": "…" }
    }
  }
}

streamable-http (remote MCP clients)

ELOG_MCP_TRANSPORT=streamable-http uv run elog-mcp

Register http://127.0.0.1:8000/mcp as a remote MCP server in your UI.

openapi (Open WebUI & friends)

ELOG_MCP_TRANSPORT=openapi \
ELOG_API_KEY=pick-a-random-secret \
uv run elog-mcp

Five read-only endpoints mirror the tools below (operationIds equal the tool names). In Open WebUI: Settings → Tools → + (user-level, fetched by your browser) or Admin Settings → Tools (global, fetched by its backend), enter the server URL, and put your ELOG_API_KEY value in the Bearer key field.

HTTPS: pass ELOG_MCP_CERTFILE/ELOG_MCP_KEYFILE, or put a reverse proxy or tunnel (e.g. cloudflared tunnel --url http://localhost:8000) in front. For locally-trusted dev certs: mkcert -install && mkcert localhost 127.0.0.1 ::1, then feed the two files to the variables above (absolute paths).

Reachability rules of thumb:

• Everything binds 127.0.0.1 by default. Set ELOG_MCP_HOST=0.0.0.0 and an ELOG_API_KEY whenever someone else must reach the server.

• Client in Docker? 127.0.0.1 inside its container is not your machine — use http://host.docker.internal:<port> (--add-host=host.docker.internal:host-gateway on Linux).

• Hosted instance (e.g. a university WebUI)? It can never reach your laptop's loopback. User-level tool servers are additionally subject to that site's Content-Security-Policy — if DevTools shows the request as Transferred: CSP, the browser blocked it and only an IT-side connect-src change helps. The practical route: deploy elog-mcp somewhere reachable and let the admins register it once as a global tool server.

Tools

Same five operations on every transport (REST routes shown for openapi):

Notes:

• Text and attribute filters are regular expressions (elogd semantics); ^value$ anchors give exact matches.

• Dates: YYYY-MM-DD[ HH:MM[:SS]], or use last_days instead of a range; logbook="*" searches all known logbooks.

• Errors surface uniformly: EntryNotFound, AuthFailed, ServerError, NetworkError, InvalidLogbook (REST status codes: 404/502/502/503/404, invalid query parameters → 400/422).

Development

uv run pytest                # unit tests, offline
uv run pytest -m live        # live suite (needs ELOG_TEST_URL)
uv run ruff check .          # lint
uv run ruff format --check . # formatting gate
uv run mypy src              # type check (strict)

Protocol details and wire-format references live in RESOURCES.md; architecture and tool contracts in SPEC.md.