Metadata-Version: 2.4
Name: mcp-zenodo
Version: 0.2.3
Summary: Model Context Protocol (MCP) server for the Zenodo open-access research repository.
Project-URL: Homepage, https://cnb.cool/xiaosicau/mcp-zenodo
Project-URL: Repository, https://cnb.cool/xiaosicau/mcp-zenodo
Project-URL: Issues, https://cnb.cool/xiaosicau/mcp-zenodo/issues
Project-URL: Original Project, https://github.com/MSKazemi/mcp-zenodo
Author: xiaoshishun
Maintainer: xiaoshishun
License: Apache-2.0
License-File: LICENSE
Keywords: doi,mcp,model-context-protocol,open-data,replication,research,zenodo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: mcp[cli]<2.0.0,>=1.6.0
Requires-Dist: numpy>=1.24
Requires-Dist: pydantic>=2.6
Requires-Dist: python-levenshtein>=0.25
Requires-Dist: scikit-learn>=1.3
Provides-Extra: all
Requires-Dist: bcrypt>=4.1; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: passlib>=1.7; extra == 'all'
Requires-Dist: python-dotenv>=1.0; extra == 'all'
Requires-Dist: python-jose>=3.3; extra == 'all'
Requires-Dist: python-multipart>=0.0.9; extra == 'all'
Requires-Dist: uvicorn>=0.27; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == 'api'
Requires-Dist: python-dotenv>=1.0; extra == 'api'
Requires-Dist: python-multipart>=0.0.9; extra == 'api'
Requires-Dist: uvicorn>=0.27; extra == 'api'
Provides-Extra: auth
Requires-Dist: bcrypt>=4.1; extra == 'auth'
Requires-Dist: passlib>=1.7; extra == 'auth'
Requires-Dist: python-jose>=3.3; extra == 'auth'
Description-Content-Type: text/markdown

# mcp-zenodo — Zenodo MCP Server

**mcp-zenodo is a Zenodo MCP server: it connects large language models to [Zenodo](https://zenodo.org/), the CERN-hosted open-access research repository, through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).** It lets an LLM search Zenodo records, read metadata, retrieve citations, and list or download files as callable tools. It is built for developers and researchers who want AI assistants to work with open research datasets, software, and publications. Use it when you want tools like Claude Desktop, Cursor IDE, or a LangChain/LangGraph agent to ground answers in real Zenodo records with DOIs. Do not use it if you need to *deposit* or *publish* to Zenodo, since this project is read/retrieval oriented and does not implement upload workflows. Compared with calling the Zenodo REST API directly, mcp-zenodo packages that access as MCP tools so any MCP-compatible client can use Zenodo without writing custom integration code.

> One-line value prop: **an MCP server for Zenodo that turns open-access research data into LLM-callable tools.**

Written in Python. Licensed under Apache-2.0.

---

## What it does

mcp-zenodo exposes Zenodo's repository of research outputs to LLMs through MCP tools:

- **Search and retrieve records** — find Zenodo records by query.
- **Get citations** — retrieve citations in formats such as BibTeX and APA.
- **Detect data types** — classify a record as dataset, software, or article.
- **Access metadata** — get detailed metadata for a record.
- **List and download files** — browse and download files attached to records.

### Available tools

| Tool | Description |
|------|-------------|
| `search_records` | Search for records in Zenodo |
| `get_metadata` | Retrieve detailed metadata of a Zenodo record |
| `get_citation` | Return a BibTeX or APA citation of a Zenodo record |
| `detect_data_type` | Determine if a record is a dataset, software, or article |
| `compare_records` | Compare metadata of multiple Zenodo records |
| `list_files` | List available files in a Zenodo record |
| `download_file` | Download a specific file from a record |
| `generate_embed_link` | Create a direct embeddable link for a record (PDF, dataset) |
| `extract_keywords` | Extract top keywords from a record's abstract or text |
| `get_related_records` | Find records related to a given Zenodo record |
| `summarize_record` | Generate a summary from a record's metadata |

---

## Package structure

Starting from v0.2.0, this repository ships as a single PyPI package (`mcp-zenodo`) with two sub-packages:

```
mcp-zenodo/
├── src/
│   ├── mcp_zenodo/          # stdio MCP server (5 tools, core)
│   │   ├── __main__.py       # entry: mcp-zenodo
│   │   ├── server.py         # FastMCP server
│   │   └── ...
│   └── mcp_zenodo_api/       # FastAPI HTTP server (11 tools, optional [api])
│       ├── __main__.py       # entry: mcp-zenodo-api
│       ├── app.py            # FastAPI app
│       └── tools/            # 11 tool modules
├── pyproject.toml
└── README.md
```

| Sub-package | Transport | Tools | Install | Entry point |
|---|---|---|---|---|
| `mcp_zenodo` | stdio (MCP SDK) | 5 core tools | `pip install mcp-zenodo` | `mcp-zenodo` |
| `mcp_zenodo_api` | HTTP (FastAPI) | 11 tools | `pip install mcp-zenodo[api]` | `mcp-zenodo-api` |

---

## 30-second quickstart

### Option A — Install from PyPI (recommended)

```bash
# Core stdio MCP server (Cursor IDE / Claude Desktop)
pip install mcp-zenodo

# Or with uvx (no install needed)
uvx mcp-zenodo

# Full installation with FastAPI HTTP server
pip install "mcp-zenodo[api]"
```

Then register the server with your MCP client. For Cursor IDE, create an `mcp.json` (in your project root or `~/.cursor/`); for Claude Desktop, add the same block to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "Zenodo": {
      "command": "uvx",
      "args": ["mcp-zenodo"]
    }
  }
}
```

Restart the client; it will detect and start the Zenodo MCP server. You can then ask the assistant to search Zenodo, fetch metadata, or retrieve a citation.

### Option B — FastAPI HTTP server for LangChain / LangGraph / OpenAI-compatible clients

```bash
# Install with API extras
pip install "mcp-zenodo[api]"

# Set up environment variables
cp .env.example .env
# Edit .env with your Zenodo API token

# Run the API server
mcp-zenodo-api --host 0.0.0.0 --port 8000

# Or via uvicorn directly
uvicorn mcp_zenodo_api.app:app --host 0.0.0.0 --port 8000
```

The FastAPI server exposes three endpoints:

- `GET /mcp/tools/openai-schema` — list all 11 tools in OpenAI function-calling format
- `POST /mcp/tools/call` — call a tool by name with arguments
- `POST /mcp/process` — process a full MCP request through the server pipeline

---

## Example

Ask an MCP-enabled assistant (Claude Desktop, Cursor) a question that triggers the `search_records` tool:

> "Search Zenodo for records about climate model output and show me the top result with its DOI."

The assistant calls the `search_records` tool, then `get_metadata`, and returns a record's title, authors, DOI, and description. A representative (abbreviated) tool result looks like:

```json
{
  "hits": [
    {
      "title": "Example Climate Model Output Dataset",
      "doi": "10.5281/zenodo.1234567",
      "type": "dataset",
      "url": "https://zenodo.org/record/1234567"
    }
  ]
}
```

You can then follow up with `get_citation` to obtain a BibTeX or APA citation, or `list_files` / `download_file` to access the record's files. (Exact fields and values depend on the live Zenodo record returned.)

---

## Use cases

- **Literature and dataset discovery** — let an AI assistant search Zenodo and surface relevant datasets, software, and papers with DOIs.
- **Citation retrieval** — pull BibTeX or APA citations for records directly into a manuscript or notebook.
- **Research agents** — give LangChain/LangGraph agents a Zenodo tool so they can ground answers in open research data.
- **In-editor research** — query Zenodo from Cursor IDE or Claude Desktop while writing code or documentation.
- **Reproducibility workflows** — locate, inspect metadata for, and download research artifacts programmatically.

---

## Comparison and alternatives

- **vs. calling the Zenodo REST API directly** — the [Zenodo REST API](https://developers.zenodo.org/) gives full control (including deposition/upload), but you must write and maintain the integration yourself. mcp-zenodo wraps common read/retrieval operations as MCP tools so any MCP client can use them with no custom code.
- **vs. general-purpose HTTP/fetch MCP servers** — a generic fetch tool can hit Zenodo URLs but has no knowledge of records, metadata, citations, or file listings. mcp-zenodo provides Zenodo-specific, typed tools.
- **vs. other research-repository MCP servers** — comparable MCP servers exist for sources such as arXiv and other data repositories; mcp-zenodo is focused specifically on Zenodo. It ships two integration paths (a stdio MCP server and a FastAPI service), which lets you choose between direct MCP clients and LLM-framework/OpenAI-compatible usage.

---

## Limitations / when NOT to use

- **Not for depositing or publishing** — this project focuses on searching and retrieving from Zenodo; it does not implement Zenodo deposition/upload workflows.
- **Depends on the Zenodo API** — availability, rate limits, and returned fields are governed by Zenodo; some operations may require a Zenodo API token.
- **Retrieval quality depends on Zenodo metadata** — data-type detection, keyword extraction, and summaries are derived from record metadata and are best-effort.
- **Two transport modes** — the stdio MCP server (`mcp-zenodo`) and the FastAPI HTTP server (`mcp-zenodo-api`) serve different use cases; pick the one matching your client.

---

## FAQ

**What is mcp-zenodo?**
mcp-zenodo is a Zenodo MCP server — an implementation of the Model Context Protocol that exposes Zenodo (the CERN open-access research repository) to large language models as callable tools for searching records, reading metadata, retrieving citations, and listing or downloading files.

**How do I use Zenodo with Claude or ChatGPT via MCP?**
For Claude Desktop or Cursor IDE, install the core stdio MCP server (`mcp-zenodo`) via `pip install mcp-zenodo` or `uvx mcp-zenodo`, and add it to your MCP client config (`claude_desktop_config.json` or `mcp.json`) as shown in the quickstart. For OpenAI-compatible / ChatGPT-style workflows, install the FastAPI sub-package with `pip install "mcp-zenodo[api]"`, run `mcp-zenodo-api` to start the HTTP service, and call its MCP-compatible tools from your framework (e.g., LangChain, LangGraph) or OpenAI-compatible client.

**Which MCP clients are supported?**
Any MCP-compatible client can use the core stdio MCP server (`mcp-zenodo`) over the standard MCP transport; it is tested with Cursor IDE and works with Claude Desktop. The FastAPI sub-package (`mcp-zenodo-api`) targets LLM frameworks such as LangChain and LangGraph, OpenAI-compatible clients, and platforms such as LibreChat.

**Do I need a Zenodo API token?**
The FastAPI service reads a Zenodo API token from `.env` (see `.env.example`). Some Zenodo operations work without a token, but a token is recommended for reliable access.

**Is mcp-zenodo on PyPI?**
Yes. Starting from v0.2.0, install with `pip install mcp-zenodo` or `uvx mcp-zenodo`. The FastAPI HTTP server is available as `pip install mcp-zenodo[api]`.

---

## Contributing

Contributions to both implementations are welcome. Please see the implementation READMEs ([mcp_sdk_core](mcp_sdk_core/README.md), [mcp_api](mcp_api/README.md)) for details.

## About this fork

This repository is a fork of [MSKazemi/mcp-zenodo](https://github.com/MSKazemi/mcp-zenodo), originally authored by **Mohsen Seyedkazemi Ardebili**.

The original project required cloning the repository and running the server manually — it did not support `uvx` one-click launch or PyPI distribution, making setup less convenient for end users. This fork repackages the project as a proper Python package (`mcp-zenodo`) published on PyPI, enabling `uvx mcp-zenodo` or `pip install mcp-zenodo` for instant use. Additional changes include:

- Full Chinese documentation (`README.zh.md`)
- Unified package structure under `src/` with `pyproject.toml` (Hatchling build)
- Qoder IDE integration guide
- Deployment on CNB (cnb.cool) for better accessibility in China

**Maintainer**: Xiao Shishun (肖诗顺), Department of Digital Economy, Sichuan Agricultural University.

---

## License

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

---

## Citation

If you use mcp-zenodo in your work, please cite it. Citation metadata is provided in [`CITATION.cff`](CITATION.cff). Example:

> Seyedkazemi Ardebili, M. *mcp-zenodo: A Zenodo MCP server.* https://github.com/MSKazemi/mcp-zenodo
>
> Xiao, S. *mcp-zenodo (CNB fork).* https://cnb.cool/xiaosicau/mcp-zenodo
