Literature Evidence MCP

Small, versioned evidence from your local papers—without loading the whole library into an AI conversation. Optional modules connect Zotero, writing projects, fixed-commit source code and experiment records.

中文说明 · Configuration · Tools · Release guide

Status: 0.5.0a1, an unreleased alpha candidate. Python 3.11+, macOS and Linux. Windows is not supported in this release (POSIX file locking/process management). No hosted account or API key is needed for local file access.

What it does

• Search local names and cached full text; retrieve text with PDF page numbers and SHA-256 hashes. Use original page images for equations and figures with Poppler.

• Return compact indexes and bounded excerpts: 4,000 text characters by default, at most 12,000 per read. Explicit continuations preserve the evidence version.

• Read live Zotero metadata in one configured collection and its descendants.

• Optionally read allowlisted writing files, save agreed review notes, inspect code at a fixed commit and exchange experiment plans/results.

The server does not modify papers, Zotero data, manuscript text or source code. MCP calls never launch an experiment. Enabled write tools save notes/plans only. Search is lexical, PDFs have no OCR, and conversation history is managed by your client. A cache avoids repeated extraction, not accumulated tool-result history.

Related MCP server: sovena

Try the bundled example

git clone https://github.com/phy-zhangzl/literature-evidence-mcp.git
cd literature-evidence-mcp

From this source checkout, with uv installed:

uv sync --locked
uv run --locked literature-mcp --config config.example.json doctor
uv run --locked literature-mcp --config config.example.json serve

serve defaults to stdio and waits for an MCP client. The example uses only the synthetic document in examples/papers and writes its cache to .state/cache. It does not use a personal Zotero library, a tunnel or an existing service config.

Install and configure

Build a wheel from a reviewed source checkout, or use a wheel attached to a future GitHub release. This candidate has not been uploaded to PyPI; do not assume the package name on a registry belongs to this project.

uv build
python3 -m venv .venv-runtime
.venv-runtime/bin/python -m pip install dist/local_literature_mcp-0.5.0a1-py3-none-any.whl
mkdir -p "$HOME/Papers"
.venv-runtime/bin/literature-mcp init --papers "$HOME/Papers"
.venv-runtime/bin/literature-mcp doctor

init creates ~/.config/literature-mcp/config.json and never overwrites an existing file. XDG_CONFIG_HOME, LITERATURE_MCP_CONFIG or the global --config argument can select another location. Relative paths are relative to the config file. Use a separate config, cache, experiment store and runtime environment for each installation. Migration from the local predecessor.

Configure your MCP client with this stdio server entry, substituting absolute paths for your runtime and config:

{
  "mcpServers": {
    "literature-product": {
      "command": "/absolute/path/to/.venv-runtime/bin/literature-mcp",
      "args": ["--config", "/absolute/path/to/config.json", "serve"]
    }
  }
}

Client configuration formats vary; this is a common stdio entry, not an automatic client installer. Optional local HTTP: add --transport streamable-http after serve. It listens on 127.0.0.1, at /mcp, with the configured port. It has no public authentication layer; do not expose it directly to the Internet.

Optional capabilities

Poppler is optional for text and required for page images. Install with brew install poppler on macOS or your distribution's poppler-utils package on Linux. Git is needed only for code tools. Zotero requires its desktop local API to be enabled. See configuration and data boundaries.

The optional foamCase adapter is for existing scientific workflows. File-only users need neither it nor a simulation environment.

Development and release

uv run --locked pytest -q
uv run --locked python scripts/smoke_test.py
uv run --locked python scripts/smoke_test.py --transport http
uv build
uv run --locked python scripts/check_release.py

Tests use synthetic fixtures and temporary stores. See CONTRIBUTING.md. CI checks macOS/Linux with Python 3.11–3.13; a configured workflow is not a claim that remote CI has already run. The tag workflow creates a draft GitHub prerelease; it does not publish to PyPI. See release guide.

License

MIT. Papers and research data remain under their own licenses and are not included in this repository.