OpenNeuro MCP Server: Neuroimaging Datasets & Metadata

Overview

The OpenNeuro MCP Server provides a searchable, machine-readable index of neuroimaging datasets and study metadata harvested from OpenNeuro. It implements a simple HTTP API that exposes dataset summaries, file lists, and study-level metadata so that tools, pipelines, and language models can discover and retrieve contextual information about brain-imaging resources programmatically.

This server is useful for developers building data discovery tools, analysis pipelines, or AI agents that need structured access to dataset descriptions (subjects, modalities, tasks, license, DOI) without downloading full data archives. By serving concise metadata and lightweight file indexes, the MCP server speeds search, enables federated tooling, and makes dataset provenance traceable in downstream workflows.

Features

• Searchable index of OpenNeuro datasets and study metadata
• Per-dataset metadata endpoints (title, DOI, license, modalities, subjects)
• Lightweight file manifests to support targeted downloads
• API endpoints suited for machine consumption (JSON), compatible with Model Context Protocol-style usage
• Docker and local-run options for quick deployment
• Simple configuration via environment variables or config file
• Logs and basic metrics for monitoring index health

Installation / Configuration

Prerequisites: Python 3.9+, git, and optionally Docker.

Clone and install:

git clone https://github.com/QuentinCody/open-neuro-mcp-server.git
cd open-neuro-mcp-server

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Environment-based configuration (example .env file):

# .env
PORT=8080
DATA_DIR=/var/openneuro/index
CACHE_TTL=3600             # seconds
LOG_LEVEL=info
MAX_SEARCH_RESULTS=100

Run locally (example using uvicorn if the server is ASGI):

export $(cat .env | xargs)
uvicorn app.main:app --host 0.0.0.0 --port ${PORT} --workers 1

Docker (build + run):

docker build -t open-neuro-mcp-server:latest .
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e DATA_DIR=/data/index \
  -v /local/index:/data/index \
  open-neuro-mcp-server:latest

Configuration options (high-level):

Available Resources

The server exposes a small set of JSON endpoints tailored for programmatic consumption. Example endpoints:

• GET /datasets — paginated list of datasets
• GET /datasets/{dataset_id} — detailed metadata for a dataset
• GET /datasets/{dataset_id}/files — file manifest for targeted downloads
• GET /search?q={query}&limit={n} — full-text search over titles, descriptions, and tags
• GET /mcp/context?dataset_id={id} — compact context bundle for use with model agents

Example: search with curl

curl "http://localhost:8080/search?q=task-rest&limit=10" \
  -H "Accept: application/json"

Example response (abridged):

{
  "total": 2,
  "results": [
    {
      "id": "ds000001",
      "title": "Resting-state dataset",
      "modalities": ["func", "anat"],
      "doi": "10.18112/openneuro.ds000001.v1.0.0"
    }
  ]
}

Use Cases

• Dataset discovery for researchers:
  • A web UI or CLI queries /search to find datasets that include a specific task or modality, then fetches dataset metadata to verify license and DOI before download.
• Pipeline-driven selective download:
  • An analysis pipeline queries /datasets/{id}/files to obtain URIs for only the required files (e.g., specific subjects or sessions), avoiding full archive transfers.
• Integration with LLM agents (MCP-style context):
  • An AI assistant uses /mcp/context?dataset_id=… to retrieve a compact context bundle describing study aims, subject counts, and preprocessing notes so the model can answer dataset-specific questions.
• Provenance and reproducibility:
  • Workflows embed dataset metadata (DOI, version) obtained from the server to create reproducible records of inputs used in analyses.

Getting Help and Contributing

Source code, issues, and contribution guidelines are available on GitHub: https://github.com/QuentinCody/open-neuro-mcp-server

To report bugs or request features, open an issue on the repository. Contributions typically follow the standard fork/branch/pull-request workflow. Include tests and update documentation when adding endpoints or changing response formats.