MCP Integration Guide

Connect Handrive to AI assistants like Claude using the Model Context Protocol (MCP).

Overview

What is MCP?

The Model Context Protocol (MCP) is a standard for connecting AI assistants to external tools and data sources. Handrive's MCP server allows AI assistants like Claude to:

Browse and search your files
Manage shares and members
Organize files with folders and tags
Transfer files between devices
Manage contacts and user profiles

Why Use MCP?

AI-Powered File Management: Ask Claude to find files, organize folders, or manage permissions
Automation: Script file operations using Claude Code
Integration: Build workflows with other tools

How It Works

The Handrive MCP server uses stdio transport, meaning it runs as a subprocess that communicates via standard input/output. This is the standard approach for Claude Desktop and Claude Code integrations.

MCP server runs via handrive mcp command
Uses local authentication (no tokens needed for stdio transport)
Provides 43 tools across 8 categories

Quick Start

Get Claude Desktop connected to Handrive:

Step 1: Authenticate Handrive

Before using MCP, you must be authenticated. Start the server and login:

# Terminal 1: Start the server
handrive serve

# Terminal 2: Login
handrive auth login otp your@email.com
# Enter OTP when prompted

Step 2: Configure Claude Desktop

Add Handrive to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "handrive": {
      "command": "/path/to/handrive",
      "args": ["mcp"]
    }
  }
}

Replace /path/to/handrive with the actual path to the Handrive binary (e.g., /usr/local/bin/handrive on Linux/macOS).

Step 3: Restart Claude Desktop

Restart Claude Desktop to load the new MCP server configuration.

Step 4: Verify Connection

In Claude Desktop, ask:

"List my Handrive shares"

Claude should respond with your shares, confirming the connection works.

Available Tools

Handrive exposes 43 tools organized into 8 categories:

Auth Tools (4)

Tool	Description
`auth_status`	Check authentication status
`request_otp`	Request OTP code sent to email
`verify_otp`	Verify OTP code to complete login
`logout`	Log out and clear credentials

Share Tools (6)

Tool	Description
`list_shares`	List all shares with optional filter (all, local, remote, discovered)
`create_share`	Create a new share from a local directory
`get_share`	Get details of a specific share
`update_share`	Update a share's name or metadata
`delete_share`	Delete a share
`is_share_online`	Check if a share's device is online

File Tools (10)

Tool	Description
`list_files`	List files in a share directory
`search_files`	Full-text search for files in a share
`get_folder_stats`	Get folder statistics (file count, total size)
`get_file`	Get details of a specific file
`update_file`	Update file tags or metadata
`delete_file`	Delete a file or directory (moves to trash)
`rename_file`	Rename or move a file
`create_file`	Create a new file with content
`create_directory`	Create a new directory
`scan_share`	Trigger a rescan of a share

Member Tools (4)

Tool	Description
`list_members`	List members of a share
`add_member`	Add a member to a share by email
`update_member`	Update a member's role
`remove_member`	Remove a member from a share

Contact Tools (5)

Tool	Description
`list_contacts`	List all contacts
`add_contact`	Add a new contact
`get_contact`	Get a specific contact
`update_contact`	Update a contact's alias
`delete_contact`	Delete a contact

User Tools (4)

Tool	Description
`get_me`	Get current user's profile
`update_me`	Update current user's profile (name, avatar, metadata)
`search_user`	Search for a user by email address
`sync_profiles`	Sync user profiles from server

Transfer Tools (9)

Tool	Description
`list_transfers`	List all transfers
`get_transfer`	Get details of a specific transfer
`cancel_transfer`	Cancel an active transfer
`restart_transfer`	Restart a failed transfer
`delete_transfer`	Delete a transfer record
`clear_transfers`	Clear all completed/failed transfers
`start_download`	Start a download transfer from a remote device
`start_upload`	Start an upload transfer to a remote device
`copy_files`	Copy files between devices

Discovery Tools (1)

Tool	Description
`discover_user`	Discover a user's available devices

Common Workflows

Exploring Shares and Files

"List my Handrive shares"

Claude uses list_shares to show all your shares.

"Show me the files in my Work share"

Claude uses list_files with the share ID.

Searching Files

"Search for PDF files in my Documents share"

Claude uses search_files with the query.

Managing Collaboration

"Add john@example.com to my Team Projects share"

Claude uses add_member with the email and share ID.

"List members of my Team Projects share"

Claude uses list_members with the share ID.

File Operations

"Create a folder called 'Q1 Reports' in my Work share"

Claude uses create_directory in the specified share.

"Rename the file 'draft.txt' to 'final.txt'"

Claude uses rename_file to change the filename.

Transfers

"Show me my current transfers"

Claude uses list_transfers to show active and recent transfers.

Claude Code Skill

If you use Claude Code, you can install the Handrive skill to get a /handrive slash command that knows all 43 MCP tools and common workflows.

Install the Skill

Copy the skill into your project's .claude/skills/ directory:

# Create the skill directory
mkdir -p .claude/skills/handrive

# Download the skill
curl -o .claude/skills/handrive/SKILL.md \
  https://handrive.app/skills/handrive/SKILL.md

Or for a personal skill available across all projects:

mkdir -p ~/.claude/skills/handrive

curl -o ~/.claude/skills/handrive/SKILL.md \
  https://handrive.app/skills/handrive/SKILL.md

Usage

Once installed, type /handrive in Claude Code followed by what you want to do:

/handrive list my shares
/handrive add editor@studio.com to the Dailies share as Editor
/handrive search for ProRes files
/handrive create a share from ~/Projects/FilmX and invite the team
/handrive check transfer progress
/handrive archive the Q4 project

Claude will use the appropriate MCP tools to carry out your request, asking for confirmation before destructive actions like deleting shares or removing members.

Requirements

Handrive must be installed and authenticated (handrive serve running)
MCP server must be configured in Claude Code (see Quick Start above)
The skill teaches Claude how to use the tools — the MCP server provides the actual tools

Troubleshooting

MCP Server Won't Start

Not authenticated:

# Check auth status (requires server running)
handrive auth status

# If not logged in, authenticate first
handrive auth login otp your@email.com

Claude Can't Find Handrive

Verify the path to handrive in your config is correct
Ensure the binary is executable (chmod +x handrive)
Restart Claude Desktop after changing the config

Tools Not Working

Ensure you're authenticated before running handrive mcp
Check that the Handrive server has network access
Verify shares exist before performing file operations