hand mcp

Run Handrive as an MCP (Model Context Protocol) server for AI assistant integration.

Synopsis

hand mcp

Description

The mcp command starts Handrive as an MCP server using stdio transport. This allows AI assistants like Claude Desktop to interact with your files, shares, and transfers through natural language.

Prerequisites

  • Handrive must be authenticated (run hand auth login otp first)
  • The server must be running (hand serve)

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Available Tools

The MCP server exposes 40+ tools across these categories:

CategoryToolsDescription
Auth5Status, login (OTP), logout, delete account
Shares6List, create, get, update, delete, online check
Files10List, search, stats, rename, delete, scan, discover
Members4List, add, update, remove
Contacts5List, add, get, update, remove
Users5Profile, update, search, invite, sync
Transfers9List, manage, download, upload, copy
Discovery1Discover shares from devices

Examples

Basic setup

# 1. Start the server
hand serve &

# 2. Authenticate
hand auth login otp your@email.com

# 3. Test MCP server manually
hand mcp
# (Ctrl+C to exit)

Using with Claude Desktop

Once configured, you can ask Claude:

  • "List my Handrive shares"
  • "Search for PDF files in my Documents share"
  • "Add alice@example.com as an editor to my Project share"
  • "Show my active file transfers"
  • "Download the report.pdf from my work share"

Troubleshooting

MCP server not responding

# Check authentication
hand auth status

# Ensure server is running
hand serve &

# Verify MCP works
hand mcp

Claude Desktop not finding Handrive

  • Verify the path to hand is correct in the config
  • Restart Claude Desktop after config changes
  • Check Claude Desktop logs for connection errors

See Also