my-lit-mcp
This server lets you manage a project-scoped literature pipeline: initialize a workspace, configure seeds and queries, search and retrieve papers from a local SQLite/PDF corpus, get recommendations, and provide feedback—all over MCP.
Initialize workspace:
ensure_workspacecreates/binds a project's.my-litdata directory.Manage queries & seeds: List configured queries; list, resolve, add, remove, and enable/disable seed papers.
Search local corpus:
search_localsearches title/abstract/fulltext;search_fulltextsearches only parsed PDF body text.Retrieve papers & full text:
get_paperreturns paper metadata with feedback/parse status;get_fulltextreturns truncated stored full text.Discover papers:
new_sincelists papers ingested after a timestamp;must_readshows high-score or must-read-labeled papers;similar_tofinds locally similar papers.Provide feedback:
mark_feedbackupserts relevant/not_relevant/must_read labels.Monitor pipeline:
pipeline_statusreports last run, OpenAlex daily calls, PDF parse counts, and seed count.
Ingests preprints and metadata from arXiv for the literature pipeline.
Ingests biomedical literature and metadata from PubMed via NCBI E-utilities.
Ingests papers and seed recommendations from the Semantic Scholar API.
Stores papers, seeds, feedback, and full text in a project-local SQLite database and supports local and full-text search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@my-lit-mcp search my local literature database for papers on diffusion models"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
my-lit-mcp
Own a free literature pipeline: ingest from Semantic Scholar, PubMed, arXiv, and OpenAlex (free daily allowance), store in project-local SQLite, download OA PDFs, extract full text with PyMuPDF, rank with your rules, and expose it to any MCP host over stdio.
Setup
brew install uv
cd my-lit-mcp
uv sync
# optional free keys (never required for arXiv)
export UNPAYWALL_EMAIL=you@example.com
export OPENALEX_API_KEY=... # free; stay within daily free search allowance
export SEMANTIC_SCHOLAR_API_KEY=... # free; improves rate limits
export NCBI_API_KEY=... # free; improves PubMed rate limits
# choose a project data dir once (prompts if omitted on a TTY)
uv run my-lit init --data-dir .my-lit
# wire MCP once at user/global scope in your MCP host (recommended):
# copy mcp.example.json into the host's user MCP config, then edit:
# absolute uv path, --directory = this my-lit-mcp install, optional API keys
# omit MY_LIT_DATA_DIR (or set it via host workspace interpolation); agents call
# ensure_workspace(project_root=...) so each project uses its own .my-lit/
# optionally edit queries in <data-dir>/config.yaml; manage seeds via MCP, not YAML
uv run my-lit ingest
uv run my-lit statusRelated MCP server: Scholar Library
Project data (not global)
Config, DB, and PDFs live under the directory you pass to init.
my-lit init --data-dir <path>:
Creates
<data-dir>/config.yaml,papers.db, andpdfs/Writes
.my-lit-pathin the project root so later CLI runs resolve the same directory
Path | Role |
| Queries, ranking, rate limits |
| Papers, seeds, feedback, full text |
| OA PDF cache |
| Marker pointing at |
Suggested: ./.my-lit inside the repo (gitignored).
Resolution order: MY_LIT_DATA_DIR → .my-lit-path → conventional ./.my-lit if it already has config.yaml. Optional overrides: MY_LIT_CONFIG, MY_LIT_DB, MY_LIT_PDF_DIR.
CLI
Command | Purpose |
| Create project-scoped config + DB + PDF cache; record path in |
| Fetch queries/seeds, Unpaywall enrich, score, optionally parse PDFs |
| Backfill OA PDF download + text extraction |
| Counts, OpenAlex calls today, last run |
Schedule ingest with the LaunchAgent example in launchd/com.my-lit.ingest.plist.example (set MY_LIT_DATA_DIR there too).
MCP registration
Intended split: user-/global-scoped MCP server + project-scoped literature DB.
Concern | Where | Why |
MCP server process | Your MCP host’s user/global config | One install of |
Papers / seeds / PDFs |
| Each project keeps its own corpus |
Commit only mcp.example.json. Absolute paths and API keys belong in local (gitignored) MCP config—not in the repo. Hosts differ on file location (user vs project vs UI); use the host’s docs. Common shapes: user/global mcp.json, project .mcp.json, or an IDE settings UI.
Recommended: user-/global-scoped MCP
Copy
mcp.example.jsoninto your host’s user/global MCP config (not into every project).Edit:
commandto an absoluteuvpath ifuvis not on the host’s default PATH (e.g.~/.local/bin/uv)args--directoryto this my-lit-mcp install (the package that runs the server)—not the host projectOptional API env vars (same values as your shell)
Prefer omitting
MY_LIT_DATA_DIRin user/global config. Agents callensure_workspace(project_root=<absolute host project path>), which creates/binds<project>/.my-lit.If your host supports workspace-path interpolation in env values, you may set
MY_LIT_DATA_DIRto that project’s.my-litinstead (still per open workspace—never a single hard-coded project path).
Do not hard-code one project’s absolute .my-lit path in user/global MCP config—that pins every workspace to a single DB.
If the same server name is also defined at project scope, many hosts let project config win. Prefer only the user/global entry for this layout.
Reload or restart MCP in your host after editing config.
uv run my-lit-mcpMCP tools: ensure_workspace, list_queries, list_seeds / resolve_seed / add_seed / remove_seed / set_seed_enabled, search_local, search_fulltext, get_paper, get_fulltext, new_since, must_read, similar_to, mark_feedback, pipeline_status.
Agents should call ensure_workspace(project_root=<host workspace>) first; it creates that project’s .my-lit when missing. See AGENTS.md.
Optional: project-only MCP
For a single-repo install, copy mcp.example.json into that project’s MCP config (e.g. .mcp.json or the host’s project MCP path). You may set MY_LIT_DATA_DIR to that project’s .my-lit absolute path when the config will never be shared across projects.
Seed management (MCP, not config files)
Seeds live in SQLite. Agents should manage them via MCP.
Tool | Purpose |
| Show saved seeds ( |
| Look up metadata by |
| Save a seed (same lookup fields as resolve); upserts by |
| Delete by |
| Disable/enable without deleting |
On my-lit ingest, enabled DB seeds drive Semantic Scholar recommendations.
API keys (all free)
Env var | Required? | Why set it |
| For OA PDF resolution | Unpaywall requires an email; no key signup |
| Only if an OpenAlex query is enabled | Free key; see OpenAlex rule below |
| No | Avoids shared-pool 429s; higher dedicated rate limits |
| No | PubMed E-utilities ~3 req/s without a key → ~10 req/s with one |
Semantic Scholar: request a free API key from Semantic Scholar’s API page. This project sends it as x-api-key on paper search and seed recommendations. Anonymous calls often work briefly, then throttle.
NCBI / PubMed: create a free NCBI account and generate an API key under account settings. Pass it as NCBI_API_KEY; it is forwarded to esearch / efetch as api_key.
Put the same env vars in your shell profile and in the MCP server env block so CLI ingest and the MCP server share them. If any are unset, ingest still runs where possible, with the limits in the table above.
OpenAlex free-tier rule
OpenAlex search uses a free API key and a hard daily call cap (openalex.max_search_calls_per_day, default 800). The pipeline stops OpenAlex for the day when the cap or HTTP 429 is hit.
Ranking
score = 0.6 * seed_hit + 0.3 * keyword_hit + 0.1 * recency, then adjust from feedback labels (relevant / not_relevant / must_read). Keyword matching can include PDF full text when match_fulltext: true.
Tests
uv run pytest -qAvailable Tools
16 toolsadd_seedC
Add or update a seed paper in the DB. Prefer s2_id or doi; title_query returns candidates.
Inputs: doi, notes, s2_id, enabled, +3 more. Returns: result
ensure_workspaceA
Create project-scoped .my-lit (config, DB, PDFs) if missing. Call this first in a new project.
Pass project_root as the absolute path of the workspace/repo using this MCP. Defaults to <project_root>/.my-lit unless data_dir or MY_LIT_DATA_DIR is set. Idempotent: safe when already initialized.
Inputs: force, data_dir, project_root. Returns: result
get_fulltextC
Return stored full text (truncated).
Inputs: paper_id (required), max_chars. Returns: result
get_paperB
Fetch one paper with feedback and parse status.
Inputs: paper_id (required). Returns: result
list_queriesB
List configured ingest queries.
Inputs: no named parameters. Returns: result
list_seedsB
List seed papers stored in the local DB (preferred over config.yaml).
Inputs: enabled_only. Returns: result
mark_feedbackC
Upsert feedback: relevant | not_relevant | must_read.
Inputs: label (required), paper_id (required), notes. Returns: result
must_readD
High-score or must_read-labeled papers.
Inputs: limit. Returns: result
new_sinceC
Papers ingested after an ISO timestamp.
Inputs: since (required), limit. Returns: result
pipeline_statusC
Last run, OpenAlex daily calls, PDF parse counts, seed count.
Inputs: no named parameters. Returns: result
remove_seedB
Delete a seed by local seed_id or Semantic Scholar s2_id.
Inputs: s2_id, seed_id. Returns: result
resolve_seedB
Look up seed candidate metadata without saving. Use before add_seed if unsure.
Inputs: doi, s2_id, arxiv_id, paper_id, +1 more. Returns: result
search_fulltextC
Search only parsed PDF body text.
Inputs: query (required), limit, source. Returns: result
search_localC
Search title/abstract/fulltext in the local corpus.
Inputs: query (required), label, limit, since, +1 more. Returns: result
set_seed_enabledB
Enable or disable a seed without deleting it.
Inputs: seed_id (required), enabled. Returns: result
similar_toD
Local title-keyword similarity.
Inputs: paper_id (required), limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools target distinct resources or actions: seed CRUD, feedback, workspace setup, and retrieval are clearly separated. The main overlap is between search_local (which includes fulltext) and search_fulltext, plus similar_to may be confused with local search, though descriptions clarify the intended scope.
Tool names consistently use snake_case and are readable, with many following verb_noun patterns like list_seeds, add_seed, get_paper, and search_local. A few names such as new_since, must_read, and similar_to deviate from verb_noun but remain understandable and stylistically consistent.
The 16 tools are just above the typical 3-15 range, but each appears to serve a specific function across workspace setup, seed management, search, retrieval, feedback, and status reporting. The set is slightly heavy but not bloated for a local literature management server.
Core seed CRUD, search, fulltext retrieval, feedback, and corpus status are covered well. However, query management is only partially exposed via list_queries with no add/remove/update tools, and there is no explicit ingestion or PDF parsing trigger, which are notable gaps for the literature workflow.
Maintenance
Related MCP Connectors
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Search PubMed/Europe PMC, fetch articles and full text (PMC/EPMC/Unpaywall), citations, MeSH terms.
Federated search of books and papers, BibTeX/RIS citations, open-access retrieval and reading.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA local academic research assistant that indexes PDFs into a searchable vector library and exposes MCP tools for semantic search, claim extraction, contradiction detection, and multi-step research synthesis.-
- AlicenseBqualityCmaintenanceEnables locally-first literature research through an MCP host by collecting sources, parsing documents, retrieving evidence, validating citations, and exporting research records in multiple formats.38MIT
- AlicenseAqualityCmaintenanceEnables an AI assistant to search scientific literature across OpenAlex and Semantic Scholar, download supported Elsevier and Springer Nature full texts, and build a local searchable index so questions can be answered with citations to original paper passages. It runs locally over stdio with CPU-based embeddings and needs no Qdrant account, Docker, GPU, or LLM API key of its own.11MIT
- AlicenseAqualityCmaintenanceEnables local literature workflows by searching arXiv, retrieving paper metadata, downloading and parsing PDFs, and retrieving page-cited body evidence for Q&A. It also exposes usage resources and templates for searching, analyzing, and summarizing papers via stdio MCP.4MIT