@perkoon/mcp

MCP server for Perkoon — P2P file transfer for AI agents. Adds send_file, receive_file, and check_session as native tools.

Files transfer directly between machines via WebRTC. Nothing touches Perkoon's servers. Free, unlimited size.

Quick Setup

Add one config block and restart. Your agent gets three new tools.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "perkoon": {
      "command": "npx",
      "args": ["-y", "@perkoon/mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "perkoon": {
      "command": "npx",
      "args": ["-y", "@perkoon/mcp"]
    }
  }
}

Cursor

Settings → MCP → Add Server → Command: npx -y @perkoon/mcp

VS Code (Copilot)

Settings → MCP → Add Server → Command: npx -y @perkoon/mcp

Windsurf

Settings → MCP → Add Server → Command: npx -y @perkoon/mcp

Tools

send_file

Send a file via P2P. Creates a session, waits for a receiver, transfers directly.

Agent: "Send the report to my colleague"
→ send_file({ file_path: "./quarterly-report.pdf" })
← Session code: K7MX4QPR9W2N
  Share URL: https://perkoon.com/K7MX4QPR9W2N
  Transfer complete! 4.2 MB in 1.3s (3.2 MB/s)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_path | string | yes | Path to the file to send | | password | string | no | Password-protect the transfer | | timeout | number | no | Seconds to wait for receiver (default: 300, max: 3600) |

receive_file

Receive files from a P2P session.

Agent: "Download from session K7MX4QPR9W2N"
→ receive_file({ session_code: "K7MX4QPR9W2N" })
← Saved to: ./received/quarterly-report.pdf
  Transfer complete! 4.2 MB in 1.3s

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | session_code | string | yes | 12-character code from the sender | | output_dir | string | no | Where to save files (default: ./received) | | password | string | no | Password if session is protected |

check_session

Check if a session is active, expired, or not found.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | session_code | string | yes | 12-character code to check |

How it works

The MCP server spawns the perkoon CLI with --json mode and parses JSONL events. No native dependencies are bundled — node-datachannel is only installed when the CLI runs. Installs in ~2 seconds.

Security

• Files paths are validated — system paths (/etc/, /proc/) and sensitive directories (.ssh/, .gnupg/) are blocked
• Symlinks are resolved before validation
• Max 5 concurrent transfers
• Passwords and timeouts are length/range-capped

Learn more

• perkoon.com — Web UI for humans
• CLI docs — npx -y perkoon@latest send file.pdf
• Agent guide — Full automation docs