digilib-mcp

DigiLIB stands for digital librarian — and this MCP server gives that ability to the agent of choice. Connect it to any MCP-capable agent (Claude Code, Claude Desktop, Codex, Antigravity, Cursor, OpenCode, and more) and that agent becomes a librarian: search academic papers and books across six free sources, and export a cited literature review as LaTeX.

No API keys. No paid services. No frontend. No TeX dependency.

Demo

digilib running in Claude Desktop. The prompt asks for recent papers on retrieval-augmented generation, two books on information retrieval, and a literature review with APA citations. Claude calls search_papers, search_books and export_research_tool, then presents the review as both a PDF and its LaTeX source.

Related MCP server: scholarfetch

Quick start

1. Run it (no install, no keys)

uvx --from git+https://github.com/cars3/digilib-mcp digilib-mcp

uvx fetches and runs the server on demand — nothing to install, nothing to configure. Python 3.10+ (verified on 3.12 and 3.14 with the mcp 2.x SDK). Or run it from a checkout:

git clone https://github.com/cars3/digilib-mcp.git
cd digilib-mcp
python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m digilib_mcp.server

2. Connect your agent

digilib registers as a standard stdio MCP server. Most clients accept:

{
  "mcpServers": {
    "digilib": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/cars3/digilib-mcp", "digilib-mcp"]
    }
  }
}

Claude Code one-liner:

claude mcp add digilib -- uvx --from git+https://github.com/cars3/digilib-mcp digilib-mcp

One-page guides with each agent's exact config file and snippet live in agent-instructions/agents/: Claude Code, Claude Desktop, Codex, Antigravity, Cursor, OpenCode, Windsurf, Qwen Code, Kimi, Grok, Copilot CLI, Pi, Hermes, legacy Gemini CLI — and a generic guide for any other MCP client.

3. Ask

"Search the literature on retrieval-augmented generation, pull two books on information retrieval, and export a literature review with APA citations."

The agent calls the tools. If it supports skills, point it at agent-instructions/SKILL.md for the query-crafting workflow.

What it exposes

Tools

• search_papers(keywords, year_from?, year_to?, size?) — OpenAlex + arXiv + Semantic Scholar + Crossref

• search_books(keywords, size?) — Open Library + Google Books

• export_research_tool(conversation_summary, literature_recommended, liked_articles?, citation_formats?) — builds and returns the LaTeX source; the calling LLM renders it

Prompt / Resource (system-prompt delivery)

• digilib_researcher prompt → the DigiLIB persona system prompt

• digilib://prompts/researcher resource → same, for resource-based clients

search_papers

search_books

export_research_tool

Both search tools return a numbered plain-text list. The header echoes the queries that were actually sent and how many hits each source contributed.

Paper search results for: transformer attention (per-source hits: openalex=10, arxiv=10, semantic_scholar=9, crossref=10)
1. Attention Is All You Need
   Authors: Ashish Vaswani, Noam Shazeer, ...
   Year: 2017
   Type: preprint | Source: arxiv
   Link: https://arxiv.org/abs/...
   Abstract: The dominant sequence transduction models are based on ...

DOI and Citations are appended to the Type line when a source provides them. Abstracts are trimmed to 300 characters.

How it works

calling agent → writes 2-5 focused search queries
                (the bundled digilib skill guides this)
              → PaperService / BookService fan out concurrently across sources
              → results normalized, deduplicated by title, returned as text
              → the agent synthesizes; can call export_research_tool to get
                the LaTeX source for the whole review

Every query goes to every source, each with a 15-second timeout, and a source that fails simply contributes nothing — the per-source hit counts in the result header show which. Duplicates are matched on lower-cased title, first occurrence wins.

The calling agent is the intelligence here: it writes the queries, reads the results, and does the synthesis. digilib is the librarian's toolkit.

For AI agents

This repository carries native instructions for coding agents:

• agent-instructions/ — all agent-facing material in one folder

• agent-instructions/AGENTS.md — the canonical guide, the only instruction file; point your agent at it directly

• agent-instructions/SKILL.md — the canonical skill, the only skill file in the repo; AGENTS.md tells every agent to read it

• agent-instructions/agents/ — per-agent connection guides

Point your agent at agent-instructions/AGENTS.md, and it will know how to set digilib up.

Configuration

Set in .env (auto-loaded, gitignored) at the repo root or inside digilib_mcp/ — see .env.example. Every setting is optional: with no configuration at all, all six sources work keyless.

The digilib_mcp/ folder is checked for .env first, and real environment variables always win over the file.

Variable names must match exactly. A misspelled name (say DIGILIB_BOOKS_APIKEY instead of DIGILIB_GOOGLE_BOOKS_API_KEY) is silently ignored, and the feature behaves as if the key were never set.

Run

# stdio (default — for desktop and CLI clients)
uv run python -m digilib_mcp.server

# HTTP (for remote agents)
DIGILIB_TRANSPORT=streamable-http uv run python -m digilib_mcp.server

Inside an activated virtualenv, plain python -m digilib_mcp.server works the same way; the installed console script is digilib-mcp. A stdio server run by hand just waits for input; it is meant to be launched by an MCP client.

Exporting research

export_research_tool returns LaTeX source and does not render a PDF. The calling LLM should save it as a .tex file (e.g. digilib_export.tex) and, if pdflatex is available, compile it:

pdflatex -interaction=nonstopmode digilib_export.tex

Without a TeX install, keep the .tex file and compile it anywhere, such as Overleaf.

The document is a 12pt A4 article titled DigiLIB Research Export, with a Literature Review (one bullet per recommended line), a Conversation Summary, and a Citations section with one numbered list per requested format (APA, Chicago, MLA). Special LaTeX characters such as &, % and _ are escaped.

Hosting as an HTTP gateway (Railway / Render / Fly)

Set DIGILIB_TRANSPORT=streamable-http and let the platform inject PORT — the server binds 0.0.0.0 and serves the MCP endpoint at /mcp. The included Procfile (web: python -m digilib_mcp.server) makes Railway zero-config: connect the repo, set the env vars, deploy, generate a domain.

Point a remote MCP client at https://<your-service>.up.railway.app/mcp:

claude mcp add --transport http digilib https://<your-service>.up.railway.app/mcp

…or in .mcp.json:

{
  "mcpServers": {
    "digilib": {
      "type": "http",
      "url": "https://<your-service>.up.railway.app/mcp"
    }
  }
}

Securing the gateway

The streamable-http transport has no built-in authentication. If you host it on a public URL without locking it down, anyone who finds the URL can call the tools. This repo ships a shared-secret bearer gate that fixes that.

1. Generate a token and set it as DIGILIB_GATEWAY_TOKEN:

python -c "import secrets; print(secrets.token_urlsafe(32))"
# e.g. pK7x...long...string

Add it to your hosting env vars (Railway → Variables). When the token is set, the server requires every request to carry Authorization: Bearer <token>; without it, requests get 401.

2. Have clients send the token. In .mcp.json:

{
  "mcpServers": {
    "digilib": {
      "type": "http",
      "url": "https://<your-service>.up.railway.app/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

If DIGILIB_GATEWAY_TOKEN is unset, the server prints a loud warning and runs unauthenticated — fine for local/LAN testing, not for a public URL.

For multi-user or third-party-client access, this shared secret isn't enough — use the MCP SDK's native OAuth 2.1 resource-server support instead (MCPServer(settings=Settings(auth=AuthSettings(...)), token_verifier=...)), which wires up BearerAuthBackend + RequireAuthMiddleware and exposes the OAuth protected-resource metadata endpoints.

Troubleshooting

• The agent doesn't show digilib. Check your agent's guide in agent-instructions/agents/ — the config paths differ per agent, and some need an absolute path to uvx. Most clients only read their config at launch, so restart the agent after editing.

• A source shows =0 in the result header. Each source fails independently and quietly, so the header is where to look. Semantic Scholar returns 429s without a key, and Google Books shares a small daily quota unless DIGILIB_GOOGLE_BOOKS_API_KEY is set.

• Google Books stays at 0 even with a key. Check the variable name is exactly DIGILIB_GOOGLE_BOOKS_API_KEY.

• Results feel thin. Query quality matters — ask for more specific terms, or let the bundled skill guide the agent's query crafting (expand acronyms, add synonyms).

• 421 Invalid Host header over HTTP. The request's Host isn't allowed. Leave DIGILIB_ALLOWED_HOSTS unset, or add your domain to it.

Sources

Notes:

• OpenAlex returns only records that have abstracts, and applies the year filters.

• arXiv is fetched with requests, because its edge WAF rejects httpx with a 406.

• Semantic Scholar gets one retry, with backoff, on a 429, and has no year filter.

• Crossref is limited to journal articles, has JATS markup stripped from abstracts, and applies the year filters.

• Open Library uses a book's first sentence as the abstract, else its subject tags.

License

MIT — see LICENSE.

Credits

• DigiLIB — short for digital librarian — is the persona and capability layer this server provides; it lives in digilib_mcp/context/researcher.md.

• Data comes from OpenAlex, arXiv, Semantic Scholar, Crossref, Open Library and Google Books.