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

• 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

# 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]"

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"

# 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

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"
      }
    }
  }
}

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

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 project:
- title: "My Research Project"
- description: "A study on..."
- public: false
- tags: ["experiment", "2024"]

# 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

# Format with black
black src/

# Lint with ruff
ruff check src/

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/

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

MIT License

Contributions welcome! Please:

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