Skip to main content
Glama
dhinalata21-ctrl

localsend-mcp

by dhinalata21-ctrl
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

LocalSend MCP

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.

Related MCP server: MCP Homescan Server

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

Available Tools

2 tools
localsend_scanA

Scan the local LAN for active LocalSend receivers and return aliases, IP addresses, ports, and protocols.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNoScan duration in seconds.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description mentions return values but does not disclose network behavior (e.g., uses UDP broadcast), permissions, or side effects. Adequate but not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with action and result. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple scan tool with one optional parameter and no output schema, the description lists return fields. Minor gap: does not specify that returns a list of devices. Still mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (timeout) with full schema description ('Scan duration in seconds'). Description does not add extra meaning beyond schema. Baseline score of 3 due to 100% coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool scans LAN for LocalSend receivers and returns specific details (aliases, IPs, ports, protocols). This distinguishes it from the sibling tool 'localsend_send' which sends files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied (scan before sending), but no explicit guidance on when to use this vs. the sibling tool. No exclusions or prerequisites mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

localsend_sendC

Send one or more absolute file paths to a LocalSend target by alias, IP, host:port, or URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
pinNoOptional receiver PIN for protected transfers.
filesYesAbsolute paths to regular files to send.
methodNoTransfer backend. auto tries direct protocol first, then localsend-cli if installed.auto
targetYesTarget alias, IP address, host:port, or http(s) URL.
timeoutNoTransfer timeout in seconds.
scan_timeoutNoAlias resolution scan duration in seconds.
busy_retry_secondsNoHow long to keep retrying when the receiver reports another active LocalSend session.
busy_retry_intervalNoSeconds to wait between busy-session retries.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It does not mention whether the operation is destructive, what happens on success/failure, authentication requirements, error states, or side effects (e.g., overwriting files). The description only states the surface-level action, leaving the agent without critical behavioral context. Score 2 reflects this significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is a single, clear, front-loaded sentence with no wasted words. It efficiently communicates the core action and target formats. However, it could be structured into a brief usage paragraph without losing clarity. Score 4 for appropriate conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 8 parameters, no output schema, and no annotations, the description is too minimal. It lacks essential context such as how the transfer works, what return values to expect, or how to interpret the parameters. For a multi-parameter tool, the description should provide an overview of the transfer flow. Score 2 indicates incomplete contextual coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, meaning all parameters have descriptions. The overall description adds minimal meaning beyond the schema: it summarizes the target format but does not elaborate on parameter usage or constraints. Baseline is 3 for high schema coverage, and the description does not elevate beyond that. Score 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (send) and the resource (file paths to a LocalSend target). It specifies the target formats (alias, IP, host:port, or URL), which is precise. However, it does not explicitly differentiate from the sibling tool 'localsend_scan', though the verb 'send' vs 'scan' makes the distinction clear. A score of 4 reflects good clarity without explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context for when to choose 'localsend_send' over 'localsend_scan'. The agent must infer usage from the tool name and verb. This lack of usage guidelines lowers the score to 2.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedlocalsend_scan
    • First observedlocalsend_send
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: one scans for receivers, the other sends files. There is no possible confusion between them.

Naming Consistency5/5

Both tools follow a consistent snake_case pattern with the 'localsend_' prefix and a clear verb: 'scan' and 'send'.

Tool Count3/5

Two tools is minimal but acceptable for a focused server that only handles scanning and sending. However, it feels thin compared to the broader file-sharing domain.

Completeness2/5

The server provides only sending capabilities; receiving files is entirely missing. This is a significant gap for a file-sharing tool, as agents cannot complete a full send-receive workflow.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Homescan Server

    aplaceforallmystuff
    A
    license
    A
    quality
    D
    maintenance
    Enables local network discovery and security scanning to identify connected devices, manufacturers, and potential risks. It allows users to track network changes and export inventories into Markdown or Obsidian-compatible formats.
    7
    21
    2
    MIT

  • HueMCP

    mbruton
    A
    license
    A
    quality
    D
    maintenance
    Enables discovery and control of Philips Hue lighting devices via a local bridge using the CLIP v2 API, without any cloud dependency.
    10
    MIT

  • imessage-send-mcp

    andyjianzhou
    A
    license
    A
    quality
    C
    maintenance
    Enables sending iMessages or SMS messages via the macOS Messages app using osascript. No Full Disk Access required, and never reads your message history.
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dhinalata21-ctrl/localsend-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server