Mdtero

Structured Markdown for research workflows.

Mdtero turns papers into reusable Markdown packages for reading, translation, project research, and local agents.

Parse a DOI or URL in one command, download structured Markdown (with a quality_label so you know when not to cite thin results), then optionally translate for bilingual reading.

Python/uv CLI, TUI, browser extension, and agent skill bundle are maintained as the public client surfaces.

Languages: English | 简体中文

Cloud MCP (ChatGPT / Claude / Cursor)

Add this remote MCP URL in ChatGPT Plugins, Claude custom connectors, or Cursor mcp.json:

https://api.mdtero.com/mcp

Sign in with a Mdtero account when asked. Save Elsevier keys at secure account settings. For institutional full text, connect Relay on an authorized campus device. An online Relay does not prove a paper is available: mdtero relay check --json checks key validity and article entitlement. See the Cloud MCP setup guide.

Codex and the ChatGPT desktop app can add this repo as a plugin source:

codex plugin marketplace add JonbinC/doi2md

The installable plugin is plugins/mdtero-reader. It points at the same public MCP service and does not include the parser.

Install

Connect an agent first (works in Cursor, Claude Code, Codex, Trae, WorkBuddy, and more):

npx skills add JonbinC/doi2md
# or: npx skills add https://mdtero.com/agent-skills

Then install the Python runtime:

uv tool install --upgrade mdtero
mdtero setup
mdtero doctor --json

The package is published on PyPI, so the default install does not depend on GitHub. In mainland China the installer automatically tries a Tsinghua/Alibaba PyPI mirror before the official index. If uv is unavailable, use the installer:

curl -Ls https://mdtero.com/install.sh | sh
curl -Ls https://mdtero.com/install.sh | sh -s -- --agent codex

The installer supports uv, pipx, and Python fallbacks. --agent <target> installs a local agent skill. Discovery index: https://mdtero.com/.well-known/agent-skills/index.json

Use Mdtero

Primary path: mdtero parse <doi-or-url> → download Markdown → optional translate. After download, check quality_label; low-confidence files use a .low_quality.md suffix.

mdtero discover "thermal energy storage" --limit 5 --interactive
mdtero parse <doi-or-url> --wait --timeout 300 --json
mdtero parse --file paper.pdf --trace --wait --timeout 600 --json
mdtero status <task-id> --wait --timeout 300 --json
mdtero download <task-id> paper_md --output-dir ./mdtero-output --json
mdtero translate <task-id> --to zh-CN --wait --timeout 600 --json

mdtero doctor --json returns safe auth/dependency/academic/Zotero/project/RAG summaries without echoing credentials.

The CLI is the default path. Desktop installs prepare the local access helper automatically for campus-network and browser-required routes. Use the browser extension only for current-page capture or when an existing browser session is needed; it can hand DOI, URL, PDF, EPUB, HTML, or XML artifacts back to the CLI.

Choose the surface for your environment

In short: a browser is required for browser-bound entitlement; a campus IP or VPN is sufficient only when the publisher exposes a machine-readable route. Mdtero never bypasses a paywall or exports browser session material.

Project Workflow

Use a local Mdtero project when you are handling a paper set:

mdtero project init --name literature-review
mdtero project import-bib references.bib --json
mdtero project parse --wait --timeout 300 --json
mdtero rag query "What are the strongest findings?" --build-if-needed --json

Zotero support is conservative: mdtero zotero sync adds Mdtero result notes and tags for matching succeeded items without rewriting Zotero bibliographic metadata.

Browser And Agents

Use the browser extension as a lightweight fallback for a paper open in your browser, content accessed through your own session, or a file you want to upload. The extension and CLI share task history, downloads, and translation.

Install a local agent skill with:

mdtero agent install --interactive
mdtero mcp briefing --json

The briefing provides safe task state, available downloads, citations, and suggested next steps. Keep API keys and other secrets out of prompts, logs, and repositories. For a trusted headless machine, enter a fresh key only at the secure mdtero setup --api-key --json prompt.

Access Boundaries

Mdtero helps process material you are permitted to access. Publisher subscriptions, institutional access, and source-specific credentials remain your responsibility. When a source needs your browser session or a local copy, use the extension or upload the saved file.

Parser and source-selection implementation are service internals, not user configuration. The stable workflow is submit, check status, download, translate, and use the resulting Markdown in a project.

Product Boundary

Mdtero Account is the control plane for Mdtero API keys, quota, billing, history, and install prompts. Academic source keys stay in local mdtero config academic configuration; OpenAlex discovery also has a server-managed fallback, so users do not need to configure an OpenAlex key just to search. The CLI-managed local access helper and browser extension remain separate from provider credentials.

Shared /api/v1 server contract

The CLI, extension, dashboard, and MCP briefing expose this contract: /api/v1/route, /api/v1/extension/route, /api/v1/tasks/parse, /api/v1/tasks/upload, /api/v1/tasks/{task_id}, /api/v1/tasks/{task_id}/download/{artifact}, /api/v1/discovery/search, /api/v1/tasks/translate, /api/v1/projects, /api/v1/projects/{project_id}/tasks/{task_id}/import, /api/v1/projects/{project_id}/rag/status, /api/v1/projects/{project_id}/rag/build, and /api/v1/projects/{project_id}/rag/query.

Repo Map

This public repository owns the Python CLI/TUI package, browser extension, campus Relay client, and public install/skill surfaces. The website/dashboard and private backend live in separate repositories.

Documentation

• Mdtero website
• Documentation
• Install guide

Development

uv run --with pytest --with rich --with textual --with httpx --with requests --with curl_cffi --with pyzotero --with fastmcp pytest tests_py -q
npm --prefix extension test
npm --prefix extension run build