OpenAIRE MCP Server

<!-- SPDX-License-Identifier: Apache-2.0 -->

MCP (Model Context Protocol) server for exploring the OpenAIRE Research Graph and ScholExplorer citation index. Enables AI assistants like Claude to discover citation relationships, find related research outputs, and retrieve comprehensive metadata for publications, datasets, and software.

Table of Contents

• Overview
• Installation
• Configuration
• Usage
  • Claude Desktop Setup
  • Available Tools
  • Example Prompts
• Development
• Operations
• License

Overview

This MCP server provides AI assistants with access to two powerful research discovery APIs:

• ScholExplorer: Citation index with 3.6 billion scholarly relationships linking publications, datasets, and software
• OpenAIRE Research Graph: Comprehensive metadata aggregator covering millions of research outputs with full abstracts, author affiliations, citation metrics, and funding information

Features

• 🔗 Find all research outputs citing a specific DOI (publications, datasets, software)
• 📊 Retrieve comprehensive metadata from OpenAIRE Research Graph
• 🤖 Seamless integration with Claude Desktop and other MCP clients
• 🐳 Docker containerization support
• 📝 Structured JSON logging
• ⚙️ Configuration via environment variables (12-factor app)

Available Tools

1. find_related_research - Find publications, datasets, and software citing a given DOI
2. get_metadata - Get detailed metadata for research products from OpenAIRE Graph

Installation

Requirements

• Python 3.10 or higher
• pip

Install from Source

# Clone the repository
git clone https://github.com/cessda/cessda.ai.mcp.openaire.git
cd cessda.ai.mcp.openaire

# Install in development mode
pip install -e .

Verify Installation

mcp-openaire --help

Configuration

The server follows the 12-factor app methodology and is configured via environment variables.

Environment Variables

Variable	Default	Description
OPENAIRE_SCHOLEXPLORER_URL	https://api.scholexplorer.openaire.eu/v3	ScholExplorer API base URL
OPENAIRE_GRAPH_URL	https://api.openaire.eu/graph/v2	OpenAIRE Graph API base URL
OPENAIRE_API_TIMEOUT	30	API request timeout (seconds)
OPENAIRE_API_MAX_RETRIES	3	Maximum retry attempts
OPENAIRE_LOG_LEVEL	WARN	Logging level (INFO, WARN, ERROR)
OPENAIRE_DEFAULT_LIMIT	200	Default citation result limit
OPENAIRE_MAX_LIMIT	1000	Maximum citation result limit
OPENAIRE_PAGE_SIZE	50	Results per API page request

Configuration File (Optional)

Create a .env file in your working directory:

OPENAIRE_API_TIMEOUT=60
OPENAIRE_LOG_LEVEL=INFO
OPENAIRE_DEFAULT_LIMIT=100

Usage

Claude Desktop Setup

1. Locate your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the MCP server configuration:

{
  "mcpServers": {
    "openaire": {
      "command": "python",
      "args": ["-m", "mcp_openaire.server"],
      "env": {
        "OPENAIRE_LOG_LEVEL": "INFO"
      }
    }
  }
}

Or if installed via pip:

{
  "mcpServers": {
    "openaire": {
      "command": "mcp-openaire"
    }
  }
}

3. Restart Claude Desktop

4. Verify the server is connected - Look for the MCP icon or check available tools

Available Tools

1. find_related_research

Find publications, datasets, and software that cite a given DOI.

Parameters:

• doi (required): DOI to find citations for (e.g., "10.21338/NSD-ESS8-2016")
• limit (optional): Max results (1-1000, default: 200)

Returns: Citation links from ScholExplorer with:

• Total citations found
• Array of citing objects with titles, authors, DOIs, publication dates
• Relationship types (cites, references)
• Object types (publication, dataset, software)
• Link providers (OpenCitations, Crossref, DataCite)

2. get_metadata

Get comprehensive metadata for a research product from OpenAIRE Research Graph.

Parameters:

• identifier (required): DOI or OpenAIRE ID (e.g., "10.2139/ssrn.3991520")

Returns: Enriched metadata including:

• Full title and abstract
• Complete author list with affiliations and ORCID IDs
• Publication date and publisher
• Citation metrics
• Access rights and open access status
• Funding information
• Subject classifications
• Access URLs

Example Prompts

Try these prompts in Claude Desktop:

1. Find citations for a dataset:

   "Find all publications citing the European Social Survey dataset 10.21338/NSD-ESS8-2016"

2. Discover related research:

   "Show me the first 50 citations for DOI 10.2139/ssrn.3991520"

3. Get detailed metadata:

   "Get me the full metadata for DOI 10.21338/NSD-ESS8-2016 including abstract and authors"

4. Explore citation network:

   "Find all research citing dataset 10.5281/zenodo.1234567 and show me the top 10 by date"

5. Combined workflow:

   "Find datasets in CESSDA about climate change, then for the first result, find all publications that cite it and get metadata for the most recent one"

Development

Setup Development Environment

# Clone repository
git clone https://github.com/cessda/cessda.ai.mcp.openaire.git
cd cessda.ai.mcp.openaire

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

Project Structure

mcp-openaire/
├── LICENSE.txt                    # Apache 2.0 license
├── README.md                      # This file
├── pyproject.toml                 # Python package configuration
├── Dockerfile                     # Container image (STDIO)
├── Dockerfile.http                # Container image (HTTP/SSE)
├── docker-compose.yml             # Docker Compose configuration
└── src/
    └── mcp_openaire/
        ├── __init__.py           # Package initialization
        ├── server.py             # FastMCP STDIO server
        ├── server_http.py        # FastMCP HTTP/SSE server
        ├── tools.py              # API integration logic
        ├── config.py             # Environment configuration
        └── logging_config.py     # Structured JSON logging

Code Standards

• Style: PEP 8 (enforced via black and ruff)
• Type Hints: Required for all public functions
• Documentation: Docstrings for all modules, classes, and functions
• Logging: Structured JSON to stdout
• Configuration: Environment variables only (no hardcoded values)
• Versioning: Semantic versioning (MAJOR.MINOR.PATCH)

Testing

# Run API integration tests
python test_api.py

# Format code
black src/

# Lint code
ruff check src/

Operations

Running in Docker

# Build image (STDIO mode)
docker build -t mcp-openaire:0.1.0 .

# Run container (STDIO mode)
docker run -i mcp-openaire:0.1.0

# Build HTTP/SSE image
docker build -f Dockerfile.http -t mcp-openaire-http:0.1.0 .

# Run HTTP server
docker run -d -p 8001:8000 mcp-openaire-http:0.1.0

# Using Docker Compose
docker compose up -d
docker compose logs -f
docker compose down

Logging

The server outputs structured JSON logs to stdout:

{
  "timestamp": "2025-01-15T10:30:45.123456Z",
  "level": "INFO",
  "message": "ScholExplorer search completed",
  "logger": "mcp_openaire",
  "doi": "10.21338/NSD-ESS8-2016",
  "total_available": 55,
  "results_returned": 55
}

Log Levels:

• INFO: Informational messages (API requests, results)
• WARN: Warnings requiring attention (validation issues, limits exceeded)
• ERROR: Errors requiring investigation (API failures, exceptions)

Monitoring

Monitor the server using:

• JSON log aggregation (ELK, Splunk, etc.)
• Check for ERROR and WARN level messages
• Track API response times and failure rates
• Monitor citation search patterns

Troubleshooting

Issue: Server not appearing in Claude Desktop

• Verify configuration file path and JSON syntax
• Check server installation: which mcp-openaire
• Review Claude Desktop logs for errors
• Restart Claude Desktop after configuration changes

Issue: API timeouts

• Increase OPENAIRE_API_TIMEOUT environment variable
• Check network connectivity to OpenAIRE APIs
• Review structured logs for timeout patterns
• Reduce OPENAIRE_DEFAULT_LIMIT for faster responses

Issue: No citations found

• Verify the DOI is correct and exists in ScholExplorer
• Not all DOIs have citations yet (especially new publications)
• Check that the DOI format is correct (starts with "10.")
• Try a well-known DOI like "10.21338/NSD-ESS8-2016" to test connectivity

Issue: Metadata not found

• Some DOIs may not be in OpenAIRE Graph yet
• Try searching ScholExplorer first to get an OpenAIRE ID
• Check the identifier format (DOI should start with "10.")

Versioning

This project uses semantic versioning:

• MAJOR: Breaking changes to API or configuration
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

Current version: 0.1.0

License

Copyright © 2025 CESSDA ERIC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See LICENSE.txt for full license text.

Links

• OpenAIRE Research Graph
• ScholExplorer
• Model Context Protocol
• FastMCP Documentation

Contributing

Contributions are welcome! Please open an issue or pull request.