Localsend

localsend-mcp gives MCP clients tools for moving files across your local network with LocalSend.

It exposes:

• localsend_scan: scan the LAN for LocalSend devices.
• localsend_send: send explicit absolute file paths to a LocalSend target.
• localsend-mcp-inbox: optional LocalSend-compatible receiver for collecting logs or small files.

The server uses the LocalSend v2 protocol directly with Python standard-library networking. No cloud relay is used.

Quick start (Cursor)

cd ~/projects/localsend-mcp
./scripts/setup.sh

Then restart Cursor. On your phone, send files to Codex MCP Inbox — the desktop LocalSend app does not need to be open.

Agent tools (in order):

1. localsend_status — is the inbox running?
2. localsend_inbox_list — what arrived?
3. localsend_inbox_read with path: "latest" — read newest text file
4. localsend_send — reply to a trusted phone alias

See AGENTS.md for the short agent workflow.

Security Warning

This MCP lets an authorized AI client request file transfers from your computer. Only install it in MCP clients you trust.

Safety controls:

• Sends require explicit absolute file paths.
• The server does not scan your folders to choose files.
• You can restrict sends and receives to trustedDevices.
• The inbox receiver is opt-in.
• The inbox receiver saves files only to a configured inbox directory.
• The inbox receiver echoes only small text-like files.
• This project transfers files; it does not run commands from other devices.

Requirements

• Python 3.10 or newer.
• LocalSend running on the target device.
• Both devices on the same local network.

Optional:

• localsend-cli on PATH, or LOCALSEND_CLI=/absolute/path/to/localsend-cli, as a fallback sender.

Install

From a local checkout:

python3 -m pip install -e .

Then configure your MCP client:

{
  "mcpServers": {
    "localsend": {
      "command": "localsend-mcp"
    }
  }
}

Without installing, you can run the server by path:

{
  "mcpServers": {
    "localsend": {
      "command": "python3",
      "args": ["/path/to/localsend-mcp/src/localsend_mcp/server.py"]
    }
  }
}

Recommended Safe Setup

First scan for LocalSend devices:

{
  "name": "localsend_scan",
  "arguments": {
    "timeout": 3
  }
}

Copy the trusted device alias and fingerprint into:

~/.config/localsend-mcp/config.json

Example:

{
  "trustedDevices": [
    {
      "alias": "Wise blackberry",
      "fingerprint": "abc123"
    }
  ],
  "inboxDir": "~/Downloads/localsend-mcp-inbox"
}

If trustedDevices is empty or omitted, the server allows discovered targets. For regular use, configure trusted devices.

Set a custom config path with:

export LOCALSEND_MCP_CONFIG=/path/to/config.json

You can also manage trusted devices through MCP:

{
  "name": "localsend_trust_device",
  "arguments": {
    "target": "Wise Blackberry"
  }
}

{
  "name": "localsend_list_trusted",
  "arguments": {}
}

{
  "name": "localsend_untrust_device",
  "arguments": {
    "alias": "Wise Blackberry"
  }
}

Sending Files

Send to a trusted alias:

{
  "name": "localsend_send",
  "arguments": {
    "target": "Wise Blackberry",
    "files": ["/home/me/Downloads/report.pdf"]
  }
}

Send to a known URL:

{
  "name": "localsend_send",
  "arguments": {
    "target": "https://111.111.1.11:53317",
    "files": ["/home/me/Pictures/image.png"],
    "pin": "123456"
  }
}

If the receiving LocalSend app is still finishing the previous transfer, localsend_send retries busy-session responses by default:

{
  "name": "localsend_send",
  "arguments": {
    "target": "Wise Blackberry",
    "files": ["/home/me/file.txt"],
    "busy_retry_seconds": 90,
    "busy_retry_interval": 3
  }
}

For phones or sleeping devices, opt into waiting for the target to come online:

{
  "name": "localsend_send",
  "arguments": {
    "target": "Rich Brocolli",
    "files": ["/home/me/file.txt"],
    "queue_if_offline": true,
    "queue_wait_seconds": 300,
    "queue_retry_interval": 5
  }
}

If the target is an iPhone or Android device, open LocalSend and keep the app awake while the queued send waits.

Optional Inbox Receiver

Start a receiver:

localsend-mcp-inbox

It advertises itself on LocalSend as Codex MCP Inbox by default and saves received files to:

~/Downloads/localsend-mcp-inbox

Change the alias:

LOCALSEND_INBOX_ALIAS="My MCP Inbox" localsend-mcp-inbox

Change the inbox directory:

localsend-mcp-inbox --dir ~/Desktop/mcp-inbox

For best compatibility with the LocalSend mobile apps, run the inbox on the default LocalSend port with HTTPS:

localsend-mcp-inbox --port 53317 --protocol https

This generates a local self-signed certificate under ~/.config/localsend-mcp/ if one does not already exist. Do not run the desktop LocalSend app on the same machine at the same time if it also needs port 53317.

Protocol request logs are quiet by default. For debugging:

localsend-mcp-inbox --port 53317 --protocol https --verbose

When trustedDevices is configured, the inbox rejects upload requests from untrusted senders.

List recent inbox files:

{
  "name": "localsend_inbox_list",
  "arguments": {
    "limit": 10
  }
}

Read the latest small text/log file:

{
  "name": "localsend_inbox_read",
  "arguments": {
    "path": "latest"
  }
}

localsend_inbox_read refuses to read outside the configured inbox and rejects binary or oversized files.

Safe Chat Mode

Chat mode treats trusted text files received in the inbox as remote prompts. It is not an autonomous command daemon: the MCP client still reads the prompt, decides what to do, and explicitly replies.

Get the latest unread trusted prompt:

{
  "name": "localsend_chat_next_text",
  "arguments": {}
}

For a simple success response, send Done and mark the prompt handled:

{
  "name": "localsend_chat_done",
  "arguments": {
    "prompt_id": "<prompt id from localsend_chat_next_text>"
  }
}

For a custom response, reply to the sender and mark the prompt handled:

{
  "name": "localsend_chat_reply",
  "arguments": {
    "prompt_id": "<prompt id from localsend_chat_next>",
    "text": "Done"
  }
}

Chat replies do not wait in a long offline queue by default. If the phone or receiver is not accepting files, the reply is saved under the chat outbox, the prompt is marked handled, and the agent should stop instead of retrying in a loop. Only set queue_if_offline: true for chat replies when the user explicitly wants the session to wait.

Use localsend_chat_next instead of localsend_chat_next_text only when full sender metadata is needed.

Mark a prompt handled without replying:

{
  "name": "localsend_chat_mark_done",
  "arguments": {
    "id": "<prompt id>"
  }
}

Chat mode requires sender metadata written by localsend-mcp-inbox. It only returns trusted text prompts by default; configure trustedDevices before relying on it.

LocalSend Tips

• LocalSend discovery uses UDP multicast 224.0.0.167:53317.
• Some networks block multicast; direct IP or URL targets may be more reliable.
• LocalSend HTTPS uses self-signed certificates. This server accepts those certificates for LAN transfers.
• LocalSend Quick Save or auto-save can avoid manual receive prompts, but enable it only for devices you trust.

Troubleshooting

No LocalSend device matched alias

Run localsend_scan, confirm both devices are on the same network, and make sure LocalSend is open.

For phones, use queue_if_offline: true and open LocalSend when you are ready to receive. Mobile operating systems may suspend LocalSend when the screen is off or the app is backgrounded.

Refusing to send to untrusted LocalSend device

Add the device alias, IP, or fingerprint to trustedDevices.

Blocked by another session

The receiver is busy with a prior LocalSend transfer. The sender retries by default, but enabling LocalSend auto-save on trusted devices helps.

Read operation timed out

The receiver may be waiting for user approval or the network may be blocking the transfer. Accept the transfer in LocalSend or increase timeout.

License

MIT