OSF MCP Server

An MCP (Model Context Protocol) server for interacting with the Open Science Framework (OSF). Search projects, registrations, preprints, manage files, and more.

Features

• Search OSF Content

  • Projects (public and private with authentication)
  • Registrations (pre-registered studies)
  • Preprints (from OSF Preprints and partner services)

• File Management

  • List project files
  • Download files with PDF-to-Markdown conversion
  • Read cached file content

• Project Management (requires authentication)

  • Create new projects
  • Update project metadata
  • Access wiki content

• DOI Resolution

  • Resolve OSF DOIs to resources

Installation

# Clone the repository
cd tools/osf-mcp-server

# Create virtual environment
uv venv
source .venv/bin/activate

# Install with dependencies
uv pip install -e ".[test]"

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | OSF_TOKEN | Personal Access Token for authenticated access | None (public only) | | OSF_STORAGE_PATH | Path for downloaded files | ~/.osf-mcp-server/files | | OSF_MAX_RESULTS | Maximum search results | 50 | | OSF_REQUEST_TIMEOUT | API timeout in seconds | 60 |

Getting an OSF Token

1. Log in to osf.io
2. Go to Settings → Personal Access Tokens
3. Create a new token with required scopes
4. Set OSF_TOKEN environment variable

export OSF_TOKEN="your_token_here"

Usage

Running the Server

# Run directly
python -m osf_mcp_server

# Or via entry point
osf-mcp-server

# With custom storage path
osf-mcp-server --storage-path /path/to/storage

Claude Desktop Integration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "osf": {
      "command": "python",
      "args": ["-m", "osf_mcp_server"],
      "env": {
        "OSF_TOKEN": "your_token_here"
      }
    }
  }
}

Or with uv:

{
  "mcpServers": {
    "osf": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/osf-mcp-server",
        "run", "osf-mcp-server"
      ],
      "env": {
        "OSF_TOKEN": "your_token_here"
      }
    }
  }
}

Available Tools

Search Tools

| Tool | Description | |------|-------------| | search_projects | Search for OSF projects by title, tags, category | | search_registrations | Search for pre-registered studies | | search_preprints | Search for preprints from OSF and partner services |

Project Tools

| Tool | Description | |------|-------------| | get_project | Get detailed project information | | create_project | Create a new project (auth required) | | update_project | Update project metadata (auth required) |

File Tools

| Tool | Description | |------|-------------| | list_files | List files and folders in a project | | download_file | Download and cache a file locally | | read_file | Read content of a downloaded file |

Other Tools

| Tool | Description | |------|-------------| | get_wiki | List or get wiki page content | | resolve_doi | Resolve an OSF DOI to a resource |

Examples

Search for Psychology Projects

Search for projects related to "cognitive bias":
- query: "cognitive bias"
- tags: ["psychology"]
- max_results: 20

Download a Research Paper

1. Search for preprints: query="machine learning"
2. List project files: project_id="abc12"
3. Download PDF: file_id="xyz789"
4. Read content: file_id="xyz789"

Create a New Project

Create project:
- title: "My Research Project"
- description: "A study on..."
- public: false
- tags: ["experiment", "2024"]

Development

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=osf_mcp_server

# Run specific test file
python -m pytest tests/test_search.py -v

Code Formatting

# Format with black
black src/

# Lint with ruff
ruff check src/

Architecture

osf-mcp-server/
├── src/osf_mcp_server/
│   ├── __init__.py          # Entry point
│   ├── server.py             # MCP server implementation
│   ├── config.py             # Configuration settings
│   ├── osf_client.py         # OSF API client
│   ├── tools/                # MCP tools
│   │   ├── search_*.py       # Search tools
│   │   ├── *_file.py         # File tools
│   │   └── ...
│   ├── resources/            # Resource management
│   │   └── osf_manager.py
│   └── prompts/              # Research prompts
│       └── research_prompts.py
└── tests/

OSF API Reference

This server uses the OSF API v2. Key endpoints:

• /nodes/ - Projects and components
• /registrations/ - Pre-registered studies
• /preprints/ - Preprints
• /files/ - File operations
• /wikis/ - Wiki pages

License

MIT License

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request