denario-mcp

A lightweight, local MCP client for Denario — an AI research assistant you drive from Claude. It runs on your machine and owns all local filesystem + git work; the private research pipeline runs remotely on Google Cloud Run and only ever returns generated data (text, PDFs), never source code.

Why a local client

Running project setup remotely could never create files on your own disk, and creating a GitHub repo from inside a container would use the server's GitHub identity, not yours. So all file and git work happens locally, under your own identity — only the confidential research compute itself is remote.

Install

pip install denario-mcp

Deliberately lightweight: it depends only on mcp and httpx, not on the Denario research stack itself — that stays entirely on the server.

git and the GitHub CLI (gh, signed in via gh auth login) are optional. Without them your project is still created and every generated file is still written to disk — only the git/GitHub side of a few tools is skipped.

Use with Claude Code

claude mcp add denario \
  -e DENARIO_API_KEY=denario_live_your_key_here \
  -e DENARIO_CLOUD_URL=https://denario-mcp-engine-tnf7nmfboa-uc.a.run.app \
  -- denario-mcp

Or, editing the MCP config by hand (~/.claude.json, or a project's .mcp.json):

{
  "mcpServers": {
    "denario": {
      "command": "denario-mcp",
      "env": {
        "DENARIO_API_KEY": "denario_live_your_key_here",
        "DENARIO_CLOUD_URL": "https://denario-mcp-engine-tnf7nmfboa-uc.a.run.app"
      }
    }
  }
}

Get an API key and the full walkthrough at denario-web.vercel.app/tutorial.

Tools

Every "local + remote" tool follows the same shape:

client (denario-mcp)                          server (Cloud Run)
  read local input file(s)
  POST /v1/compute/<step>  ─────────────────►   run the pipeline in an ephemeral dir
  ◄─────────────────────────────────────────    { artifacts, log[, result] }
  write artifacts into the local project dir
  git commit (and push, if enabled — see below)

The server never touches your disk or your git identity; this client owns both. Long steps (like denario_paper) are handled transparently whether the server runs them synchronously or as an async job it polls to completion — nothing to configure on your end.

GitHub integration is opt-in

By default, nothing is pushed to GitHub — every step commits locally only. Set DENARIO_GITHUB_PUSH=1 to have denario_setup create a GitHub repo under your own identity and have each step push after committing. denario_publish is the one exception: it always pushes, since publishing is an explicit action regardless of that setting.

Environment

Development

pip install -e ".[test]"
python -m pytest -m "not live"

That last flag skips the one opt-in test that hits a real deployment (gated separately by DENARIO_LIVE_TEST=1, so it never runs by accident).