# LocalTools MCP

A stdio [MCP](https://modelcontextprotocol.io) server for **Claude Desktop** that gives Claude three local capabilities:

1. **Interactive media player** that renders *inside* Claude Desktop (audio and video) with play, pause, seek and volume controls.
2. **Local command runner** to run shell commands on your machine.
3. **Local file tools** to read, write and edit files.

Built with [FastMCP](https://gofastmcp.com).

## What makes the player different

The player is a real [MCP App](https://modelcontextprotocol.io/extensions/apps/overview): when Claude calls `play_media`, Claude Desktop renders an HTML5 player in a sandboxed iframe right in the conversation, no external window or browser tab.

To keep media bytes out of the model context (a base64 video would blow up the context window), the server streams the file over a small local HTTP server bound to `127.0.0.1` with HTTP range support, so seeking works. The tool result only carries a tiny pointer (title, kind, mime, local URL) that the player loads.

If the host's content policy blocks the direct stream, the player falls back to fetching the file as a blob, and finally offers an "Open in browser" button.

## Tools

| Tool | What it does |
| --- | --- |
| `play_media(source, title="")` | Play a local audio/video file (absolute path) or an `http(s)` media URL in the in-app player. |
| `run_command(command, cwd="", timeout=120)` | Run a shell command, returns exit code, stdout and stderr. |
| `read_file(path, offset=0, limit=0)` | Read a text file with 1-based line numbers. |
| `write_file(path, content, overwrite=True)` | Write a file, creating parent directories. |
| `edit_file(path, old_string, new_string, replace_all=False)` | Exact substring replace in a file. |

## Requirements

- Python 3.10+
- Claude Desktop (for the in-app player; the other tools work in any MCP client)

## Install

```bash
pip install -r requirements.txt
```

Register it with Claude Desktop using the FastMCP CLI (it edits the Claude Desktop config for you):

```bash
fastmcp install claude-desktop server.py --with nanoid
```

Then restart Claude Desktop.

### Manual config

Alternatively add this to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "local-tools": {
      "command": "python",
      "args": ["C:\\path\\to\\server.py"]
    }
  }
}
```

## Usage

Just ask Claude, for example:

- "Play `C:\Users\me\Music\song.mp3`"
- "Play this video D:\clips\demo.mp4"
- "Run `git status` in my project folder"
- "Read the first 40 lines of server.py"
- "In config.json change the port from 8080 to 9090"

## Notes

- The media server uses a fixed local port pool (`8770-8789`); the first free port is chosen at startup.
- On Windows, `run_command` runs through `cmd.exe`; on macOS/Linux it uses your shell.
- Everything runs locally. The command runner and file tools have full access to your machine, so only enable this server if you trust the client driving it.

## License

MIT, see [LICENSE](LICENSE).