@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.

The wrapper sets PERKOON_SOURCE=agent_mcp in the spawn env, so all MCP traffic attributes correctly to the MCP runtime in Perkoon's analytics (distinct from raw CLI / browser / A2A traffic). Agents that discovered Perkoon via the published SKILL.md can override that with PERKOON_SOURCE=agent_skill if discovery attribution matters more than transport.

Verifying the install

MCP hosts probe the package before launching it over stdio. You can do the same:

npx -y @perkoon/mcp --version   # prints the version and exits
npx -y @perkoon/mcp --help      # prints the tool list + a config snippet

Server override (self-hosted / local dev)

The CLI honors PERKOON_URL for self-hosted Perkoon and local dev. To point the MCP server at a non-production instance:

{
  "mcpServers": {
    "perkoon": {
      "command": "npx",
      "args": ["-y", "@perkoon/mcp"],
      "env": { "PERKOON_URL": "https://dev.perkoon.com" }
    }
  }
}

Security

• File 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

Limits

Perkoon enforces per-IP rate limits on session endpoints (10 creates, 30 joins, 20 status checks per minute). The server returns HTTP 429; the CLI surfaces this as a failed transfer, so a send_file/receive_file call may return isError: true with a "Too many requests" message. It's transient — wait ~60s and retry, it's not a configuration problem.

Learn more

• perkoon.com — Web UI for humans
• CLI docs — npx -y perkoon@latest send file.pdf
• Agent guide — Full automation docs (Protocol 01 / 02, A2A JSON-RPC, MCP, browser flows)
• SKILL.md — Drop-in Claude Skill for skills/perkoon/SKILL.md or .claude/skills/perkoon/