crossref-cite-mcp 0.1.0

MCP tool for resolving paper citations via Crossref API with multiple format support

crossref-cite-mcp

A Model Context Protocol (MCP) server for resolving paper citations via Crossref API. Supports multiple output formats including CSL-JSON, BibTeX, RIS, and formatted text.

Features

• 🔍 Smart Input Parsing: Automatically detects DOIs, arXiv IDs, PMIDs, or falls back to bibliographic search
• 📚 Multiple Citation Formats: CSL-JSON, BibTeX, RIS, and formatted text (APA, Chicago, IEEE, etc.)
• ⚡ Built-in Caching: Memory or JSON file cache with configurable TTL (default: 14 days)
• 🔄 Retry Logic: Exponential backoff for rate limits (429) and server errors (5xx)
• 🎯 Polite Pool Support: Uses mailto parameter for higher Crossref rate limits

Installation

# Clone the repository
git clone https://github.com/h-lu/crossref-cite-mcp.git
cd crossref-cite-mcp

Using uv (Recommended)

# Install dependencies
uv sync

# Install with dev dependencies
uv sync --extra dev

Using pip

# Install from source
pip install .

# Or install in editable mode (for development)
pip install -e ".[dev]"

Configuration

Set environment variables (or create a .env file):

# Required: Your email for Crossref polite pool
export CROSSREF_MAILTO=[e-mail]

# Optional: Cache configuration
export CROSSREF_CACHE_BACKEND=json        # "memory" or "json"
export CROSSREF_CACHE_PATH=~/.crossref-cite/cache.json
export CROSSREF_CACHE_TTL=1209600         # 14 days in seconds

# Optional: Logging
export LOG_LEVEL=INFO

Usage

As MCP Server (Claude Desktop / Cursor)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

Using uv

{
  "mcpServers": {
    "crossref-cite": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/crossref-cite-mcp", "python", "-m", "crossref_cite"],
      "env": {
        "CROSSREF_MAILTO": "[e-mail]"
      }
    }
  }
}

Using pip (after pip install .)

{
  "mcpServers": {
    "crossref-cite": {
      "command": "python",
      "args": ["-m", "crossref_cite"],
      "env": {
        "CROSSREF_MAILTO": "[e-mail]"
      }
    }
  }
}

Available Tools

resolve_citation

Resolve a paper and return citations in multiple formats.

Arguments:

• query (required): Paper title, DOI, arXiv ID, or PMID
• formats: List of formats (["csl-json", "bibtex", "ris", "formatted"])
• style: CSL style for formatted output (default: "apa")
• locale: Locale for formatted output (default: "en-US")
• rows: Number of Crossref candidates (default: 5)

Example:

{
  "query": "Attention Is All You Need",
  "formats": ["bibtex", "formatted"],
  "style": "apa"
}

search_papers

Search Crossref for papers (metadata only, no citation fetching).

Arguments:

• query (required): Search query
• rows: Number of results (default: 10, max: 20)
• filter_from_year: Publication year filter (start)
• filter_to_year: Publication year filter (end)
• filter_type: Work type filter (e.g., "journal-article")

Direct CLI Testing

# Test with JSON-RPC request
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"resolve_citation","arguments":{"query":"10.1038/nature12373","formats":["bibtex"]}}}' | python -m crossref_cite

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=crossref_cite

# Lint
ruff check src tests

# Type check
mypy src/crossref_cite

Recording VCR Cassettes

To record new HTTP interaction cassettes for tests:

# Delete existing cassettes and re-record
rm -rf tests/cassettes/
pytest tests/ -v --vcr-record=new_episodes

Docker

# Build image
docker build -t crossref-cite-mcp .

# Run
docker run -e CROSSREF_MAILTO=[e-mail] crossref-cite-mcp

API Reference

Crossref Best Practices

This implementation follows Crossref REST API best practices:

• ✅ Uses mailto parameter for polite pool access
• ✅ Implements exponential backoff for rate limits
• ✅ Caches results to reduce redundant requests
• ✅ Uses query.bibliographic for citation-like searches

Content Negotiation

Citation formats are fetched via DOI content negotiation:

Format	Accept Header
CSL-JSON	application/vnd.citationstyles.csl+json
BibTeX	application/x-bibtex
RIS	application/x-research-info-systems
Formatted	text/x-bibliography; style=apa; locale=en-US

License

MIT