What is MCP?

The Model Context Protocol (MCP) is a standard for connecting AI assistants to external tools and data sources. It allows AI models to safely interact with files, databases, and APIs on your behalf.

Handrive's MCP server gives AI tools like Claude Code access to your Handrive shares — allowing the AI to read files, list directories, and help with file-related tasks.

Why Use Handrive with AI?

Access shared project files: Let Claude Code read documentation, code, or data from your Handrive shares
Cross-device workflows: Files shared via Handrive are accessible to AI tools on any device
Privacy: Files stay on your devices, not uploaded to AI training data

Prerequisites

Handrive installed and running
Authenticated with your Handrive account
Claude Desktop or another MCP-compatible AI tool

Step 1: Verify Handrive Server is Running

The Handrive server must be running and authenticated before starting the MCP server:

# Check authentication status
handrive auth status

# If not logged in:
handrive serve --port 3001 &
handrive auth login otp your@email.com

Step 2: Configure Claude Desktop

Add Handrive to your Claude Desktop configuration. Edit the config 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 your Handrive binary (e.g., /usr/local/bin/handrive or /Applications/Handrive.app/Contents/MacOS/handrive).

Step 3: Restart Claude Desktop

After saving the config, restart Claude Desktop. You should see Handrive listed as an available MCP server.

Available MCP Tools

Once connected, Claude can use these Handrive tools:

Share Management

list_shares — List all your shares
get_share — Get details about a specific share
create_share — Create a new share

File Operations

list_files — List files in a share
get_file — Get file details and metadata
create_file — Create a new file with content
delete_file — Delete a file

Member Management

list_members — List members of a share
add_member — Add a member to a share
remove_member — Remove a member

Example Usage

Once configured, you can ask Claude things like:

"List all my Handrive shares"
"Show me the files in my Project share"
"Read the README.md file from my Documentation share"
"Who has access to my Team Files share?"

Claude will use the MCP tools to access your Handrive data and provide relevant information or take actions.

Security Considerations

Local only: The MCP server runs locally on your machine. Your files aren't uploaded anywhere.
Authentication required: You must be logged into Handrive for the MCP server to work.
Same permissions: The AI can only access shares you have access to.

Troubleshooting

MCP server not connecting

Verify Handrive is authenticated: handrive auth status
Check the path to the Handrive binary is correct
Look at Claude Desktop logs for errors

"Not authenticated" error

Make sure you've logged in with handrive auth login otp and the server is running.

Get Started with Handrive

Download Handrive and connect your files to AI workflows.

Download Handrive