# localbridge

**Let AI clients use the apps on your Mac, locally, with your permission.**

localbridge is a small MCP server that runs on your Mac and gives AI clients tools for Mail, Calendar, Reminders,
Notes, your files and (optionally) Microsoft Teams. A menu bar app shows what it is doing.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/images/menu-dark.png">
    <img src="docs/images/menu-light.png" alt="The localbridge menu bar panel" width="520">
  </picture>
</p>

## What it can do

- **Mail**: search (full text, in under a second), read, draft, reply, forward, move, flag.
- **Calendar & Reminders**: list, create, update and delete events and reminders.
- **Notes**: search, read, create and edit Apple Notes.
- **Files**: search with Spotlight, read PDFs and documents, move, rename, write; deleting means moving to the Trash.
- **Teams** *(optional)*: chats, channels, search and meeting transcripts, limited to an allowlist and historical depth you choose.

Anything that reaches other people (sending an email or a Teams message, changing a meeting with attendees)
**always asks for your confirmation**. Text from emails, messages and files is marked as
third-party content, so the AI treats it as data, not as instructions.

## Install

Requires macOS 14 or later, [uv](https://docs.astral.sh/uv/) and the Xcode Command Line Tools
(`xcode-select --install`).

```bash
git clone https://github.com/contessid/localbridge.git
cd localbridge
scripts/install.sh                      # installs the service and the menu bar app
uv run scripts/register_clients.py all  # adds localbridge to Claude Code and Codex
```

Then give **Full Disk Access** to `~/Applications/Localbridge.app` (System Settings → Privacy & Security →
Full Disk Access), which Mail's data needs. Calendar, Reminders and Automation are asked the first time they are
used. The menu bar icon shows anything that is still missing, with a button to fix it.

## Settings

Everything is in the menu bar app → **Settings…**: turn services on or off, choose the folders the file tools may
use, connect Microsoft 365, register AI clients, and see the activity log (tool name, time and result, never the
content).

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/images/settings-services-dark.png">
    <img src="docs/images/settings-services-light.png" alt="Services settings" width="49%">
  </picture>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/images/settings-teams-access-dark.png">
    <img src="docs/images/settings-teams-access-light.png" alt="Teams access settings" width="49%">
  </picture>
</p>

## Teams (optional)

Teams works through Microsoft Graph with delegated permissions: localbridge sees only what you see, and only what
you put in the **Teams access** allowlist, each entry with its own history limit. It needs an app registered in
your Microsoft 365 tenant: see the [setup guide](docs/clients.md#teams-microsoft-365).

## Privacy

- The server listens only on `127.0.0.1`, protected by a token.
- No telemetry, no cloud relay; logs stay in `~/Library/Logs/localbridge`.
- macOS permissions belong to `Localbridge.app`, not to your terminal.

## Uninstall

```bash
scripts/uninstall.sh            # removes the apps and their background agents, keeps your settings
scripts/uninstall.sh --purge    # also deletes settings, indexes and the Microsoft 365 session
```

## More

- [Full guide](docs/clients.md): clients, permissions, every tool, settings.
- [macOS internals](docs/notes/macos-internals.md) and [Microsoft Graph notes](docs/notes/microsoft-graph.md).

## License

[MIT](LICENSE)