Skip to main content
Glama

Research Notebook MCP

An MCP server that turns any BOSS agent into a research assistant. It gives your agent (Claude Code, Codex, Gemini, OpenCode - anything BOSS drives) a set of tools to capture cited sources, keep linked notes, and export a bibliography or a literature-review outline - all stored as plain files inside the project you are working in.

Point it at a project, browse and read as usual, and ask your agent to "cite this page", "note down why this matters", or "draft an outline of what I have so far". The notebook is a single human-readable notebook.json plus the Markdown and BibTeX files it generates, so nothing is locked away.

Why this helps researchers

The expensive part of a literature review is not reading, it is keeping track: where a fact came from, which paper made which claim, and how a pile of notes turns into a structured draft. A general chat agent forgets all of this between turns. This server gives the agent a durable, structured memory built around the two things a researcher actually accumulates:

  • Sources you cite, with real bibliographic metadata (title, authors, date, journal or site, DOI) extracted automatically from the page.

  • Notes you write, each linked to the sources behind it.

From those it can produce a BibTeX file for LaTeX/Overleaf, an annotated bibliography, or a literature-review outline that groups your notes by theme and threads in the right citations.

Related MCP server: terminal_kb

The tools

Tool

What it does

cite_url

Fetch a URL, extract its metadata, and save it as a source (de-duplicates by URL; adds your quote/tags to an existing source).

add_source

Record a source by hand (a book, or a page you cannot fetch).

update_source

Correct or enrich a source's fields.

add_quote

Attach an excerpt (with page/location and your comment) to a source.

add_note

Write a Markdown research note linked to the sources it draws on.

update_note

Edit a note's title, content, tags, or links.

list_sources / list_notes

List sources or notes, optionally filtered by tag (or by linked source).

get_source / get_note

Show full detail of one item, including quotes.

search

Full-text search across sources and notes.

remove_source / remove_note

Delete an item (removing a source unlinks it from notes and reports which).

export_bibtex

Render sources as BibTeX, optionally writing references.bib.

export_markdown

Render a Markdown bibliography (plain or annotated), optionally writing references.md.

generate_outline

Assemble notes into a literature-review scaffold, optionally writing outline.md.

notebook_stats

Counts of sources, notes, quotes, tags, and types.

Quick start

git clone https://github.com/Rushikeshiitb/boss-research-notebook-mcp.git
cd boss-research-notebook-mcp
npm install
npm run build

Run it directly (it speaks MCP over stdio):

RESEARCH_NOTEBOOK_DIR="$PWD/.research-notebook" node dist/index.js

Or install it on your PATH as research-notebook-mcp (the package declares a bin):

npm install -g .          # from the cloned repo
# now `research-notebook-mcp` launches the server over stdio

Cite keys

Sources get a human-friendly citation key in the usual author-year-word style, for example vaswani2017attention. Collisions are disambiguated with a trailing letter (smith2020a, smith2020b). You can refer to any source by either its cite key or its internal id in every tool that takes a source.

Connecting it to BOSS

BOSS drives coding CLIs (Claude Code, Codex, Gemini, OpenCode), and each of them loads MCP servers from its own configuration - so you register this server with the CLI you use inside BOSS. It is a stdio server: the client launches it and talks over stdin/stdout.

Project-scoped config file (portable across clients). Drop a .mcp.json in the root of the project you open in BOSS:

{
  "mcpServers": {
    "research-notebook": {
      "command": "node",
      "args": ["/absolute/path/to/boss-research-notebook-mcp/dist/index.js"],
      "env": {
        "RESEARCH_NOTEBOOK_DIR": "/absolute/path/to/your/project/.research-notebook",
        "RESEARCH_NOTEBOOK_TITLE": "My Literature Review"
      }
    }
  }
}

Claude Code, one command (run it in your project directory):

claude mcp add research-notebook \
  -e RESEARCH_NOTEBOOK_DIR="$PWD/.research-notebook" \
  -- node /absolute/path/to/boss-research-notebook-mcp/dist/index.js

If you installed it globally (npm install -g .), the command is simply research-notebook-mcp in place of node .../dist/index.js.

Once connected, the 17 tools above appear to your agent alongside the rest of the tools it can call.

Configuration

Variable

Default

Purpose

RESEARCH_NOTEBOOK_DIR

<cwd>/.research-notebook

Folder holding notebook.json and the generated exports.

RESEARCH_NOTEBOOK_TITLE

(unset)

Sets the notebook title on first run, used in export headings.

What gets written

Everything lives in the notebook directory:

  • notebook.json - the canonical store (sources and notes). Written atomically (unique temp file + rename) under an advisory lock.

  • references.bib - BibTeX, when you ask export_bibtex to write.

  • references.md - Markdown bibliography, when you ask export_markdown to write.

  • outline.md - the literature-review scaffold, when you ask generate_outline to write.

Because it is all plain text in your project, it version-controls cleanly and you can read or edit it without the server. Every source and note needs a non-empty id; the server normalises array fields on load (missing ones become empty, tags are lowercased and de-duplicated, unknown keys are kept) and refuses to start if an entry cannot be read at all.

Editing it while the server runs: the server loads notebook.json once and writes the whole document back on each change. If the file changes on disk underneath it - you hand-edited it, or a second server shares the directory - the next write is refused rather than silently overwriting your edit: the server reloads the on-disk version and returns a conflict error asking you to re-apply your change. A refused or failed write never corrupts the file or the in-memory copy. Writes are serialized by a lock file, so two servers on one directory take turns instead of clobbering each other.

Example workflow

  1. cite_url on a paper you are reading, with a quote and tags: ["method"].

  2. add_note capturing your take, linked to that source.

  3. Repeat while you read.

  4. generate_outline to get a themed draft with citations threaded in.

  5. export_bibtex to drop references.bib into your LaTeX project.

Privacy and safety

  • The only outbound request the server makes is cite_url fetching a page. Because the agent, not you, picks that URL, the fetch is hardened against being pointed at your own network (SSRF):

    • only http/https;

    • the hostname is resolved and every address it returns is checked - the request is refused if any is loopback, private, link-local (cloud metadata at 169.254.169.254), CGNAT or IPv6 loopback/ULA/link-local/mapped-private;

    • the connection is pinned to the validated address, so a name cannot be re-resolved to a private address after the check (DNS-rebinding);

    • redirects are followed manually and each hop is re-validated, so a public page cannot bounce the fetch to an internal one;

    • the response body is capped (5 MiB) and the fetch gives up after 30 s. Nothing else leaves your machine.

  • All data is stored locally in the notebook directory. There is no external service and no telemetry.

  • A failed or blocked fetch is reported cleanly; you can always fall back to add_source to record a citation by hand.

Development

npm run typecheck   # tsc --noEmit
npm test            # vitest: unit + in-memory MCP integration tests
npm run build       # emit dist/

The test suite covers metadata extraction (OpenGraph, Google Scholar / highwire citation_* tags, JSON-LD, and degenerate pages), cite-key generation and collisions, the notebook store and its persistence, BibTeX and Markdown rendering, and a full end-to-end pass driving the real MCP server over an in-memory transport with a stubbed fetch.

Layout

src/
  types.ts      data model (sources, notes, notebook)
  metadata.ts   pure HTML -> bibliographic metadata extraction
  citekey.ts    author-year-word cite keys, with de-duplication
  notebook.ts   the store: CRUD, search, atomic persistence
  bibtex.ts     BibTeX export
  markdown.ts   bibliography + literature-review outline
  server.ts     MCP tool registration (fetch and store injected)
  index.ts      stdio entry point

License

Apache-2.0, matching the BOSS Console core.

Available Tools

17 tools
add_noteAdd a research noteA

Write a research note in Markdown and link it to the sources it draws on. Notes are the raw material generate_outline turns into a literature-review scaffold.

Inputs: title (required), content (required), tags, sources.

add_quoteAdd a quote to a sourceB

Attach an excerpt (optionally with a page/location and your comment) to a source.

Inputs: text (required), source (required), note, page.

add_sourceAdd a source manuallyA

Record a source by hand - a book, a paper you have the details for, or a page you cannot fetch. Use this when cite_url is not possible.

Inputs: title (required), doi, url, tags, +5 more.

cite_urlCite a web pageA

Fetch a URL, extract its bibliographic metadata (title, authors, date, journal/site, DOI) and save it as a source. If the URL is already saved, it is not duplicated; any quote/note you pass is added to the existing source instead. This is the fastest way to capture a citation while browsing.

Inputs: url (required), note, tags, type, +1 more.

export_bibtexExport BibTeXB

Render sources as BibTeX. Optionally filter by tag and/or write the result to references.bib next to the notebook.

Inputs: tag, write.

export_markdownExport a Markdown bibliographyB

Render a Markdown bibliography. Set annotated to include summaries and quotes. Optionally filter by tag and/or write references.md next to the notebook.

Inputs: tag, title, write, annotated.

generate_outlineGenerate a literature-review outlineA

Assemble your notes into a Markdown literature-review scaffold: notes grouped by theme, each threaded with the cite keys it draws on, plus a References section and a 'not yet written up' list. Optionally filter by tag and/or write outline.md next to the notebook.

Inputs: tag, title, write.

get_noteGet a noteB
Read-only

Show the full content of one research note.

Inputs: id (required).

get_sourceGet a sourceB
Read-only

Show the full detail of one source, including its quotes.

Inputs: source (required).

list_notesList notesA
Read-only

List research notes, optionally filtered by tag or by a linked source.

Inputs: tag, source.

list_sourcesList sourcesB
Read-only

List all saved sources, optionally filtered by tag.

Inputs: tag.

notebook_statsNotebook statisticsA
Read-only

Summarise the notebook: counts of sources, notes, quotes, tags, and types.

Inputs: no named parameters.

remove_noteRemove a noteC
Destructive

Delete a research note.

Inputs: id (required).

remove_sourceRemove a sourceA
Destructive

Delete a source. Any notes that linked to it keep their text; the broken link is dropped and reported.

Inputs: source (required).

update_noteUpdate a research noteB

Edit a note's title, content, tags, or linked sources. Omitted fields are unchanged.

Inputs: id (required), tags, title, content, +1 more.

update_sourceUpdate a sourceB

Correct or enrich a source's bibliographic fields. Omitted fields are unchanged.

Inputs: source (required), doi, url, tags, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose. Verbs like list, get, add, update, remove target specific resources (sources vs notes), and cite_url vs add_source are well-differentiated by their descriptions. No two tools appear to do the same thing.

    Naming Consistency5/5

    Consistent verb_noun pattern throughout (search, remove_source, export_bibtex, get_source, list_notes, add_quote, generate_outline, etc.). Minor variation for 'search' and 'notebook_stats' but still predictable and readable.

    Tool Count4/5

    17 tools is slightly heavy but appropriate for a research notebook's broad functionality (sources, notes, quotes, exports, outline generation). Each tool earns its place without excessive overlap.

    Completeness5/5

    Full CRUD lifecycle for sources and notes, plus specialized operations like cite_url, add_quote, exports, outline generation, and stats. No obvious gaps for the stated domain.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to maintain a folder-scoped research wiki for scientific papers by providing MCP tools for full-text search, reading, note creation, tagging, logging, and PDF ingestion, all without requiring its own LLM API key.
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables local agents to search and retrieve cited evidence from PDFs and Markdown notes, including page-specific passages and rendered page images.
      6
      GPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to create verifiable, replayable citations, search private knowledge bases, and publish Markdown with verified citation markers.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to search and query a local knowledge base of scattered notes and docs through hybrid vector plus BM25 retrieval with section-level citations, and to store, retract and explore durable memories, note links and agent harness memories. It also exposes note resources plus briefing, study-plan and contradiction-check prompts, all backed by a shared local index.
      -