Metadata-Version: 2.5
Name: endnote-mcp
Version: 1.4.12
Summary: Connect your EndNote reference library to Claude AI — search, cite, and read PDFs directly in conversations
Project-URL: Homepage, https://github.com/gokmengokhan/endnote-mcp
Project-URL: Documentation, https://github.com/gokmengokhan/endnote-mcp#readme
Project-URL: Repository, https://github.com/gokmengokhan/endnote-mcp
Project-URL: Issues, https://github.com/gokmengokhan/endnote-mcp/issues
Author: Gokhan Gokmen
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: academic,bibliography,citation,claude,endnote,literature,mcp,pdf,references,research
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: lxml>=5.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pymupdf>=1.24
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.2.0; extra == 'semantic'
Requires-Dist: sqlite-vec>=0.1.0; extra == 'semantic'
Description-Content-Type: text/markdown

# EndNote MCP

[![Tests](https://github.com/gokmengokhan/endnote-mcp/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/gokmengokhan/endnote-mcp/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/endnote-mcp)](https://pypi.org/project/endnote-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/endnote-mcp)](https://pypi.org/project/endnote-mcp/)
[![License](https://img.shields.io/pypi/l/endnote-mcp)](https://github.com/gokmengokhan/endnote-mcp/blob/main/LICENSE)

<!-- mcp-name: io.github.gokmengokhan/endnote-mcp -->

Connect your EndNote reference library to Claude AI. Search references, read PDFs, format citations, find related papers, and generate bibliographies — all directly in Claude Desktop conversations.

## What It Does

Once set up, you can ask Claude things like:

- *"Search my library for social capital and Bourdieu"*
- *"Find papers about how organisations deal with uncertainty"* (semantic search)
- *"Find references related to paper #3844"*
- *"Give me the APA citation for reference #1234"*
- *"Generate a bibliography for references 12, 45, 78, 102"*
- *"Export references 12, 45, 78 as BibTeX"*
- *"Read pages 5-7 from that Smith et al. paper"*

Claude searches your **local** library — nothing is uploaded to the cloud beyond the normal conversation.

## How It Works

```
EndNote Library → XML Export → endnote-mcp index → SQLite Database (FTS5 + Embeddings)
                                                          ↕
                                   Claude Desktop ← MCP Server (12 tools)
```

Your references and PDF text are indexed into a local SQLite database with full-text search. Optionally, AI embeddings enable semantic search — finding papers by meaning, not just keywords. When semantic dependencies are installed, new references are automatically embedded during indexing. Claude connects through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

## Requirements

- **EndNote 20+** (any edition)
- **Claude Desktop** app

The bundle installer below has no other prerequisites — Claude Desktop manages Python and dependencies. The CLI install path additionally needs Python 3.10+ and uv (or pip).

## Install (Desktop Bundle — Recommended)

The fastest install for non-engineers. No Python or terminal required.

1. **Export your library from EndNote.** File → Export → choose **XML** format → save somewhere like Desktop.
2. **Download** `endnote-mcp.mcpb` from the [latest release](https://github.com/gokmengokhan/endnote-mcp/releases).
3. **Double-click the `.mcpb` file** (or in Claude Desktop: Settings → Extensions → Install Extension…).
4. In the install dialog, point Claude Desktop at:
   - Your **EndNote XML** file (from step 1)
   - Your **PDF Attachments Folder** — usually `<library>.Data/PDF/` next to your `.enl` file, or `PDF/` inside an `.enlp` package.
5. Click Install. Claude Desktop will start indexing your library automatically — metadata is searchable within seconds, PDF text and semantic embeddings finish in the background.

That's it. Try asking Claude *"Search my library for grounded theory"*.

The bundle keeps its own configuration (`config-mcpb.yaml`), so installing it will not disturb an existing CLI setup. Both default to the same database, so if you already indexed with the CLI the bundle reuses that index rather than building a second copy.

### Building the bundle yourself

Maintainers (or anyone working from source) can build it with:

```bash
bash scripts/build_mcpb.sh
# → dist/endnote-mcp.mcpb
```

The build is a single cross-platform `.mcpb` file (~36 KB). Dependencies resolve at install time via the `uv` runtime bundled with Claude Desktop.

> The format was called DXT and used the `.dxt` extension until it was renamed upstream to MCPB (MCP Bundles). See [modelcontextprotocol/mcpb](https://github.com/modelcontextprotocol/mcpb).

## Install (CLI / from PyPI)

Prefer the terminal? This path gives you the `endnote-mcp` CLI for indexing and embedding.

### 1. Install

```bash
# With uv (recommended)
uv tool install endnote-mcp

# Or with pip
pip install endnote-mcp
```

### 2. Export your library from EndNote

In EndNote: **File → Export** → choose **XML** format → save to a convenient location (e.g., Desktop).

### 3. Run the setup wizard

```bash
endnote-mcp setup
```

The wizard will:
- Auto-detect your XML export and PDF directory
- Create the configuration
- Index your library
- Configure Claude Desktop automatically

### 4. Restart Claude Desktop

Quit and reopen Claude Desktop. You'll see "EndNote Library" in your MCP connectors.

## Semantic Search (Optional)

Enable meaning-based search that finds references even when they use different terminology than your query. For example, searching *"how companies prepare for uncertain futures"* finds papers on scenario planning and strategic foresight.

```bash
# Install semantic search dependencies
pip install endnote-mcp[semantic]

# Generate embeddings (~3 min for 4,000 references)
endnote-mcp embed
```

This uses the lightweight [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) model locally — no API keys needed, everything stays on your machine.

## Commands

| Command | What It Does |
|---------|-------------|
| `endnote-mcp setup` | Interactive setup wizard |
| `endnote-mcp index` | Re-index after adding new references (incremental) |
| `endnote-mcp index --full` | Full re-index from scratch |
| `endnote-mcp index --skip-pdfs` | Index metadata only (fast, ~1 sec) |
| `endnote-mcp index --embed` | Re-index and generate embeddings |
| `endnote-mcp embed` | Generate semantic search embeddings |
| `endnote-mcp embed --full` | Regenerate all embeddings from scratch |
| `endnote-mcp status` | Show index statistics |
| `endnote-mcp install` | Add to Claude Desktop config |
| `endnote-mcp serve` | Start MCP server (used by Claude Desktop automatically) |

## Tools Available to Claude

| Tool | Description |
|------|-------------|
| `search_references` | Search by author, title, year, keywords, abstract (BM25 ranked, with DOI links) |
| `search_fulltext` | Search inside PDF content — find concepts, quotes, methods |
| `search_library` | Combined metadata + PDF search in one call |
| `search_semantic` | Search by meaning using AI embeddings (requires `endnote-mcp[semantic]`) |
| `get_reference_details` | Full metadata for a reference (abstract, keywords, DOI, etc.) |
| `get_citation` | Format as APA 7th, Harvard, Vancouver, Chicago, or IEEE |
| `get_bibtex` | Export references as BibTeX entries for LaTeX |
| `get_bibliography` | Generate a formatted bibliography for multiple references |
| `find_related` | Find similar references (uses embeddings when available) |
| `read_pdf_section` | Read specific pages from a PDF attachment |
| `list_references_by_topic` | Broad topic-based listing |
| `rebuild_index` | Re-index after updating your EndNote library |

## Adding New References

When you add new references to your EndNote library:

1. **Re-export XML** from EndNote (overwrite the same file)
2. Either:
   - Run `endnote-mcp index` from a terminal, **or**
   - Ask Claude: *"Rebuild my library index"*

Indexing is **incremental** — it only processes new references and PDFs, not the entire library again. If semantic search is installed, new references are automatically embedded.

## Performance

| Operation | Time (4,000 references) |
|-----------|------------------------|
| Metadata indexing | ~1 second |
| PDF extraction (first time) | ~1 min per 100 PDFs |
| PDF extraction (incremental) | Only new PDFs |
| Embedding generation | ~3 minutes |
| Keyword search | < 50 ms |
| Semantic search | < 200 ms |

## Configuration

Config is stored at:
- **macOS**: `~/Library/Application Support/endnote-mcp/config.yaml`
- **Windows**: `%APPDATA%/endnote-mcp/config.yaml`
- **Linux**: `~/.config/endnote-mcp/config.yaml`

```yaml
endnote_xml: /path/to/your/library.xml
pdf_dir: /path/to/your/Library.Data/PDF
db_path: /path/to/library.db    # auto-set by setup
max_pdf_pages: 30                # max pages per read request
search_notes: false              # include the EndNote Notes field in searches
```

### Notes fields

EndNote's **Research Notes** — where you keep your own summaries and judgments —
is indexed and searched by default, ranked just below keywords and above the
abstract.

The plain **Notes** field is indexed but excluded from matching, because
reference managers use it as a dumping ground on import: author affiliations,
email addresses, thesaurus terms. Set `search_notes: true` to include it. The
setting takes effect immediately — no re-index needed.

## Citation Styles

Five built-in styles:

- **APA 7th** — `get_citation(rec_number=42, style="apa7")`
- **Harvard** — `style="harvard"`
- **Vancouver** — `style="vancouver"`
- **Chicago** (Author-Date, 17th ed.) — `style="chicago"`
- **IEEE** — `style="ieee"`

Use `get_bibliography` to format multiple references at once, sorted by author or year.

## BibTeX Export

Export references as BibTeX entries for use in LaTeX:

- Ask Claude: *"Export references 42 and 100 as BibTeX"*
- Or use the `get_bibtex` tool directly with comma-separated record numbers

Generates complete entries with proper entry types (`@article`, `@book`, `@inproceedings`, etc.), cite keys, and all available fields.

## Troubleshooting

**"No configuration found"** — Run `endnote-mcp setup`

**"XML file not found"** — Re-export from EndNote: File → Export → XML format

**"PDF not found"** — Check that `pdf_dir` in your config points to the correct `.Data/PDF` directory

**Search returns no results** — Run `endnote-mcp index` to rebuild the database

**Claude Desktop doesn't show the tool** — Run `endnote-mcp install`, then restart Claude Desktop

**"Semantic search is not available"** — Run `pip install endnote-mcp[semantic]` then `endnote-mcp embed`

**Client reports the server "failed to connect" / `CONNECTION_CLOSED`** — The client hides the underlying error. Run `echo '' | endnote-mcp serve` to see the real traceback (the JSON decode error it prints afterwards is just the empty input, not a fault).

## Releasing

Publishing runs on a tag push via [`.github/workflows/release.yml`](.github/workflows/release.yml), which uploads to PyPI and the MCP Registry using OIDC — no API tokens are stored in the repository.

The version lives in seven places, and the registry rejects a `server.json` that does not exactly match the published PyPI release. Bump all of them, then verify before tagging:

```bash
# pyproject.toml, server.json (x2), CITATION.cff, the README citation
# block, mcpb/manifest.json and mcpb/pyproject.toml
python scripts/check_version.py v1.4.12

git commit -am "Bump version to 1.4.12"
git tag v1.4.12 && git push origin main --tags
```

## Citing This Software

If you use this tool in your research, please cite it:

> Gokmen, G. (2026). *EndNote MCP: Connecting EndNote Reference Libraries to Claude AI* (Version 1.4.12) [Computer software]. https://doi.org/10.5281/zenodo.18617546

Or use the "Cite this repository" button on GitHub for BibTeX/APA formats.

## License

AGPL-3.0 — free to use, modify, and distribute. See [LICENSE](LICENSE) for details.
