# Fenn MCP server

Give Claude Code access to your Fenn location, conversations, messages, and calendars through the [Model Context Protocol](https://modelcontextprotocol.io) — read-only by default, with message sending only through a token you explicitly mint with send access.

```bash
npx @fenn-chat/mcp-server@0.2.0 setup
```

## Get the Fenn app and a token

You need the Fenn iOS app and a remote-access token from it:

1. Download **Fenn — Family Organizer** from the App Store: <https://apps.apple.com/app/id6761315757>, and sign in with your phone number.
2. In the app, open your **Profile** and tap **Remote access**.
3. Tap **+ Create token** and name it (for example "Claude on my laptop"). Where your app version offers the choice, pick **Read-only** or **Read & send messages** (older versions mint read-only tokens).
4. Copy the token — it is shown **once**. Deleting it in that list revokes access immediately.
5. Run the setup command above and paste the token into its masked prompt.

## What setup does

Setup explains what Claude will be able to do, asks for your Fenn token in a masked prompt, checks it with Fenn, stores it in your operating-system credential store, registers the server with Claude Code (user scope, pinned to this exact version), and verifies that Claude can start it and see all eight tools. The token never appears on the command line, in shell history, in logs, in MCP responses, or in Claude's configuration files.

Then, in Claude Code, try:

- “Where am I right now?”
- “What did I discuss with Alex recently?”
- “What is on my calendar tomorrow?”

Claude Code asks for approval before it uses a Fenn tool for the first time (the tools show up as `mcp__fenn__fenn_me`, `mcp__fenn__fenn_list_conversations`, and so on; `/mcp` lists the server). Restart any Claude Code session that was open during setup.

Check the installation any time:

```bash
npx @fenn-chat/mcp-server@0.2.0 doctor
```

## What Claude can do

The server exposes exactly eight tools: seven read-only ones and one send.

| Tool | Reads |
| --- | --- |
| `fenn_me` | Your profile, time zone, and current location state |
| `fenn_list_conversations` | Your conversations, their members, and the latest message |
| `fenn_get_conversation_messages` | A page of messages from one conversation |
| `fenn_search_messages` | Semantic message-search results |
| `fenn_get_member_locations` | Current locations that people share with you |
| `fenn_get_member_location_history` | Your own history and history people explicitly share with you |
| `fenn_get_calendar_events` | Your events, and calendar details or availability shared with you |
| `fenn_send_message` | **Sends** a plain-text message as you into one of your conversations — only with a token that has send access |

A token minted as **Read-only** (`account.read`) lets Claude see everything you can see in Fenn and change nothing; `fenn_send_message` then returns an error explaining how to mint a send token. A token minted as **Read & send messages** (`account.write`) additionally lets Claude send plain-text messages as you; Claude Code asks you to confirm every single send (the tool is marked as requiring user interaction, which overrides "always allow"), and the message is written with a marker that it came through remote access. Other people's location, history, and calendars are limited to what they chose to share with you, and Fenn enforces that on the server for every request. There is no other write, and no resource, prompt, sampling, filesystem, or shell access.

## Requirements

- Claude Code 2.0 or later (tested with 2.1.251) for the one-command setup. Other stdio MCP clients work too; see [Other clients](docs/OTHER_CLIENTS.md).
- Node.js 22.22.3 or later; Node 22 and 24 LTS are tested.
- A Fenn account with Remote access: [get the app](https://apps.apple.com/app/id6761315757) and create or delete tokens in **Fenn → Profile → Remote access → + Create token**, choosing **Read-only** or **Read & send messages** where offered. The token is shown once, never expires, and deleting it in Fenn revokes access immediately. You can have up to ten tokens.
- A credential store: macOS Keychain (tested), Windows Credential Manager (supported by the prebuilt binary, not yet tested), or a Linux Secret Service such as GNOME Keyring or KWallet.

## How the token is stored

`setup` stores the raw token in the OS credential store as service `fenn-mcp`, account `fenn-remote-access-token`, and reads it only when the server handles its first tool call. Nothing is ever written to a plain file, `~/.claude.json`, `.mcp.json`, or a shell profile. If the credential store is unavailable, setup stops before asking for the token.

On macOS the item is created by the `node` binary that ran setup; if Claude Code later launches a different Node (for example after switching versions), macOS may ask whether `node` may access “fenn-mcp” — choose **Always Allow**.

For unattended environments there is an explicit override: `FENN_TOKEN` in the environment that launches `fenn-mcp serve`. It is authoritative when set (a malformed value is an error, not a fallback) and is never persisted by this package. See [Other clients](docs/OTHER_CLIENTS.md).

## Rotate, upgrade, uninstall

```bash
npx @fenn-chat/mcp-server@0.2.0 rotate      # paste a new token; it is validated before the old one is replaced
npx @fenn-chat/mcp-server@<new version> setup   # upgrade: re-registers Claude Code with the new pinned version
npx @fenn-chat/mcp-server@0.2.0 uninstall   # shows what will be removed and asks first
```

Rotation: create a new token in Fenn, run `rotate`, then delete the old token in Fenn. Running servers pick up the new token on their next call.

Uninstall removes only the Claude Code user-scope server named `fenn` and the `fenn-mcp` credential. It does not revoke the token in Fenn (delete it there), touch other MCP servers, modify projects, or clear the npx cache (`npm cache clean --force` if you want that too).

## Troubleshooting

`doctor` reports package and Node versions, credential-store availability, whether a token is configured and where it comes from (never its value), the Claude Code version and registration, whether the server starts with exactly eight tools, and a direct `fenn_me` check with remediation. `doctor --json` prints the same redacted report.

Common cases — details in [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md):

- **401 / “token revoked”**: create a new token in Fenn and run `rotate`.
- **429 / quota**: Fenn allows 1000 units per day and 60 per minute, and at most 100 sent messages per day; the error says when to retry. Searching or reading locations across “all” conversations costs more than one conversation.
- **“This token is read-only and cannot send messages”**: mint a token with send access in Fenn and run `rotate`.
- **Tools missing in Claude Code**: run `doctor`, restart Claude Code, check `/mcp`.
- **Server fails to start / npx cannot download**: the first launch after install or upgrade needs network access to fetch the pinned version once.

## Other MCP clients

The server is a plain stdio MCP server:

```json
{ "command": "npx", "args": ["-y", "@fenn-chat/mcp-server@0.2.0", "serve"] }
```

It reads the token from the OS credential store written by `setup` (run setup once, even without Claude Code — it stops at the Claude step if `claude` is missing, after storing nothing) or from `FENN_TOKEN`. See [docs/OTHER_CLIENTS.md](docs/OTHER_CLIENTS.md) for Claude Desktop, Cursor, and the MCP Inspector.

## Trust model and privacy

- The server is a local process that runs as you, launched by your MCP client. Install only versions you trust; releases are published from this repository with npm provenance.
- It talks only to `https://fenn.chat` over HTTPS with `Authorization: Bearer <token>`.
- No telemetry, analytics, or crash reporting. Fenn's API keeps token last-used and quota accounting.
- Setup and doctor print only booleans and status — never your uid, name, coordinates, messages, or events. Sends require an explicitly minted send token and a confirmation in Claude Code for every message.
- This package does not consume Claude, Anthropic, or OpenClaw credits; the cost of Claude reading tool results is part of your normal Claude usage.

See [docs/SECURITY.md](docs/SECURITY.md) and [docs/CLAUDE_CODE.md](docs/CLAUDE_CODE.md).

## Roadmap

A hosted Streamable HTTP endpoint with browser sign-in (no token pasting) is planned; the tool layer is already separated from the transport and the credential code so it can be reused there. No release date is promised.

## Development

```bash
git clone https://github.com/fenn-chat/fenn-mcp.git
cd fenn-mcp
npm ci
npm run check
```

Tests use deterministic fake tokens, stubbed HTTP, an in-memory credential store, and a fake `claude` CLI; they never touch your keychain, your Claude configuration, or production Fenn. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT