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

Handrive works like network file sharing on your OS, but over the internet. You connect to contacts, see their shared folders, and transfer files directly — never through servers.

The 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 hand mcp command
• Uses local authentication (no tokens needed for stdio transport)
• Provides 40+ 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
hand serve

# Terminal 2: Login
hand 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 40+ tools organized into 8 categories:

Auth Tools (5)

Share Tools (6)

File Tools (10)

Member Tools (4)

Contact Tools (5)

User Tools (5)

Transfer Tools (9)

Discovery Tools (1)

Common Workflows

Sharing Files (you → others)

"Create a share from ~/Projects/Design"

Claude uses create_share to share a folder. Files stay on your machine.

"Add john@example.com as an editor to my Design share"

Claude uses add_member to grant access by email.

Receiving Files (others → you)

"Find shares from sarah@example.com"

Claude uses add_contact → discover_shares → discover_files → list_files to find and browse their shared files.

Exploring Your Shares

"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 40+ 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.ai/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.ai/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 (hand 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)
hand auth status

# If not logged in, authenticate first
hand 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 hand mcp
• Check that the Handrive server has network access
• Verify shares exist before performing file operations

See Also

• CLI Reference — CLI commands including hand mcp
• Headless Guide — Running Handrive without GUI
• Troubleshooting — General troubleshooting