mineru-mcp: Instructions file for Claude Code

mineru-mcp

MCP server for MinerU document parsing API — PDF/DOC/PPT/images to markdown.

Quick Reference

• Language: TypeScript/Node
• Package manager: bun
• Build: bun run build (outputs to dist/)
• Dev: bun run dev (tsx, stdio mode)
• Entry: src/index.ts (stdio) / src/server.ts (HTTP)

API Key Management

• Provider: MinerU (OpenXLab) — https://mineru.net
• Format: JWT token (Bearer auth)
• Expiry: Tokens auto-expire after ~90 days from issuance
• Don't hard-code the expiry date here — a stale one is worse than none. (This line used to read "Current key expires: 2026-05-19" and sat ~2 months past that, presenting an expired key as current.) Read the real expiry from the token itself:

  # decode the JWT payload -> exp (unix seconds)
  python3 -c "import base64,json,os,sys;t=os.environ['MINERU_API_KEY'].split('.')[1];print(json.loads(base64.urlsafe_b64decode(t+'='*(-len(t)%4)))['exp'])"
  

• Config location: ~/.claude.json under mcpServers.mineru.env.MINERU_API_KEY (appears in both global and project-level entries)
• Env var: MINERU_API_KEY
• Troubleshooting 401: almost always an expired token. Decode exp (above); tokens are not refreshable — generate a new one at mineru.net and update both the global and project-level entries in ~/.claude.json.

Architecture

Single-file server (src/index.ts, ~695 lines) with 6 tools:

Tool	Purpose	Flow
mineru_parse	Parse single URL	Returns task_id
mineru_status	Check task progress	Poll with task_id
mineru_batch	Parse multiple URLs (preferred)	Returns batch_id
mineru_batch_status	Check batch progress	Poll with batch_id
mineru_upload_batch	Upload local files (slow, use URLs when possible)	Returns batch_id
mineru_download_results	Download named paper folders	Uses batch_id, saves to output_dir

URL workflow (preferred)

mineru_batch (array of public URLs — arXiv, SSRN, publisher sites)
  → mineru_batch_status (poll until all done)
  → mineru_download_results (extracts named paper folders)