# ReferenceMCP

Academic Reference Manager MCP server for Claude Desktop. Search papers, manage references, and format citations in 10,000+ styles.

## Features

- **Search** across Crossref, Semantic Scholar, OpenAlex, and PubMed
- **Save** references to a local SQLite database
- **Organize** with collections and tags
- **Format** citations in APA, MLA, Chicago, IEEE, Harvard, and thousands more CSL styles
- **Export** to BibTeX, RIS, or CSL-JSON

## Installation

### Using uv (Recommended)

```bash
git clone https://github.com/eduardofarina/ReferenceMCP.git
cd ReferenceMCP
uv sync
```

### Using conda

```bash
conda env create -f environment.yml
conda activate reference-mcp
pip install -e .
```

## Configuration

1. Copy `.env.example` to `.env`:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` with your settings (all optional but recommended):
   ```env
   CONTACT_EMAIL=your@email.com
   ```

3. Add the server to your MCP client config.

   **Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
   ```json
   {
     "mcpServers": {
       "reference-mcp": {
         "command": "uv",
         "args": [
           "--directory",
           "<path-to-ReferenceMCP>",
           "run",
           "server.py"
         ]
       }
     }
   }
   ```
   Replace `<path-to-ReferenceMCP>` with the full path to your clone (e.g. `C:\Users\You\ReferenceMCP` on Windows or `/home/you/ReferenceMCP` on Linux/macOS).

   **Cursor** (`.cursor/mcp.json`): use the same `command` and `args`, with your project path in `--directory`.

## Available Tools

### Search Tools

| Tool | Description |
|------|-------------|
| `search_papers` | Search across sources by query |
| `search_by_doi` | Look up a paper by DOI |
| `get_paper_details` | Get full metadata for a saved reference |
| `get_citations` | Get papers that cite a given paper |
| `get_references` | Get papers cited by a given paper |

### Library Management

| Tool | Description |
|------|-------------|
| `save_reference` | Save a paper by DOI |
| `list_references` | List saved references |
| `delete_reference` | Remove a reference |
| `create_collection` | Create a collection |
| `add_to_collection` | Add reference to collection |
| `tag_reference` | Add tags to a reference |
| `list_collections` | List all collections |
| `list_tags` | List all tags |

### Citation Formatting

| Tool | Description |
|------|-------------|
| `format_citation` | Format a reference in a style |
| `format_bibliography` | Format multiple references |
| `list_styles` | List available styles |
| `set_default_style` | Set default citation style |

### Export

| Tool | Description |
|------|-------------|
| `export_bibtex` | Export as BibTeX |
| `export_ris` | Export as RIS |
| `export_csl_json` | Export as CSL-JSON |

## Example Usage

**User**: "Find papers about transformer architectures and save the top result"

**Claude**:
1. Searches with `search_papers(query="transformer architectures")`
2. Saves with `save_reference(doi="10.48550/arXiv.1706.03762")`

**User**: "Format my saved papers as an APA bibliography"

**Claude**:
1. Lists with `list_references()`
2. Formats with `format_bibliography(reference_ids=[1,2,3], style="apa")`

## Testing

Test with MCP Inspector:
```bash
uv run mcp dev server.py
```

## Citation Styles

Popular styles included:
- APA (7th Edition)
- MLA (9th Edition)
- Chicago (Author-Date & Notes-Bibliography)
- IEEE
- Harvard
- Vancouver
- Nature, Science, Cell
- And 10,000+ more from the CSL repository

## Data Storage

References are stored in `data/references.db` (SQLite). Citation styles are cached in `styles/`.

## License

MIT