# Zenodo MCP Server

[![Python CI](https://github.com/Agostynah/Zenodo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Agostynah/Zenodo-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An official Model Context Protocol (MCP) server for discovering, retrieving, citing, and evaluating scientific records from the [Zenodo](https://zenodo.org/) repository. This server enables AI agents (like Claude, Cursor, GitHub Copilot, Windsurf) to find open science data, verify licensing, explore versions, construct citations, and reason over research bundles natively.

## Quick Start

### 1. Guided Setup (Zero Install with `uv`)
The fastest way to get started is using `uvx` (the package runner from `uv`):
```bash
uvx zenodo-mcp --setup
```
The interactive wizard will automatically detect installed MCP clients (Claude Desktop, Cursor, OpenCode, VS Code, Windsurf, etc.), guide you through optional Zenodo API token setup, and write the necessary JSON configuration files for you.

### 2. Alternative Installation
If you don't have `uv` installed, you can install the package globally using `pip`:
```bash
# Install package
pip install zenodo-mcp

# Launch guided setup
zenodo-mcp --setup
```

---

## Features & Available Tools

The server exposes **17 MCP tools** categorized into Core, Advanced, and AI-Native:

### Core Tools
*   `search_records`: Search Zenodo records using full Elasticsearch syntax.
*   `search_by_community`: Filter and search records inside a specific community (e.g. `cern`).
*   `search_by_funder`: Search for records funded by a grant agency (e.g. `NSF`, `EC`).
*   `get_record`: Retrieve complete metadata, abstracts, statistics, and authors.
*   `list_files`: List files associated with a record, returning direct download URLs (fully read-only, safe, no disk writes).
*   `related_records`: Extract related record IDs grouped by connection type.
*   `resolve_doi`: Resolve a DOI or DOI URL to its metadata record.
*   `cite_record`: Generate standard citations (APA, MLA, Harvard, Chicago, BibTeX, RIS).
*   `export_metadata`: Export metadata in JSON, YAML, BibTeX, or RIS formats.
*   `latest_version`: Fetch the version timeline and latest edition of any record.

### Advanced Tools
*   `search_by_license`: Search for records filtered by SPDX licenses (e.g. `MIT`, `CC-BY-4.0`).
*   `inspect_license`: Retrieve permissions (commercial use, attribution, copyleft, modification) for a given license.
*   `compare_records`: Perform a side-by-side comparison of two records' sizes, formats, metrics, and dates.
*   `recommend_dataset`: Rank datasets matching a natural language prompt using metadata quality and downloads metrics.

### AI-Native Stretch Tools (Research Helpers)
*   `find_training_datasets`: Recommend machine learning training datasets based on modality, license terms, and size constraints.
*   `generate_data_card`: Synthesize an AI-friendly dataset summary card (similar to Hugging Face Data Cards).
*   `evaluate_reusability`: Grade a dataset's reusability score (0-100) based on FAIR principles.
*   `build_research_bundle`: Assemble linked paper, dataset, and code assets into a unified reproducibility package.

---

## Configuration Reference

You can configure the server using environment variables or a `.env` file in the directory where the server is executed:

| Environment Variable | Default | Description |
|---|---|---|
| `ZENODO_API_URL` | `https://zenodo.org/api` | API URL (use `https://sandbox.zenodo.org/api` for sandbox) |
| `ZENODO_ACCESS_TOKEN` | *None* | Optional token for higher rate limits (100 vs 25 results/page) |
| `CACHE_ENABLED` | `true` | Enables in-memory TTL cache |
| `TRANSPORT` | `stdio` | Transport protocol: `stdio` (local subprocess) or `sse` (network) |
| `SSE_HOST` | `127.0.0.1` | Bind address for SSE mode |
| `SSE_PORT` | `8000` | Port for SSE mode |
| `REQUEST_TIMEOUT` | `30` | Network request timeout in seconds |
| `LOG_LEVEL` | `INFO` | Level of logging (outputs to `stderr` to protect transport channel) |

---

## Client Integration Guide

The setup wizard handles this for you, but if you prefer manual configuration, add the following to your client's config file:

### Local stdio Mode (Default)
```json
{
  "mcpServers": {
    "zenodo": {
      "command": "zenodo-mcp"
    }
  }
}
```

### Network SSE Mode (e.g., Docker / Remote Host)
```json
{
  "mcpServers": {
    "zenodo": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

### File Locations:
*   **Claude Desktop**:
    *   Windows: `%APPDATA%\Claude\claude_desktop_config.json`
    *   macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
*   **Cursor**:
    *   Global: `~/.cursor/mcp.json`
    *   Project: `.cursor/mcp.json`
*   **OpenCode**:
    *   Global Config: `~/.opencode/mcp.json`
    *   Windows Path: `%USERPROFILE%\.opencode\mcp.json`
*   **VS Code**:
    *   `~/.vscode/mcp.json`
*   **Windsurf**:
    *   `~/.windsurf/mcp.json`
*   **Continue.dev**:
    *   `~/.continue/config.json` (inside `"mcpServers"` block)

---

## Docker Deployment

You can build and run the Zenodo MCP Server as a Docker container.

### 1. Build the image
```bash
docker build -t zenodo-mcp .
```

### 2. Run in Local stdio Mode
```bash
docker run -i zenodo-mcp
```

### 3. Run in SSE Network Mode
```bash
docker run -p 8000:8000 zenodo-mcp --transport sse --host 0.0.0.0 --port 8000
```

---

## Contributing & Development

We use `uv` for dependency management:

```bash
# Clone the repository
git clone https://github.com/Agostynah/Zenodo-mcp.git
cd Zenodo-mcp

# Initialize virtualenv and install dependencies
uv venv
uv pip install -e ".[dev]"

# Run tests
uv run pytest --cov=zenodo_mcp -v

# Run MCP Inspector for interactive debug
npx -y @modelcontextprotocol/inspector uv run zenodo-mcp
```

## License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.