Fenn MCP server

Give Claude Code access to your Fenn location, conversations, messages, and calendars through the Model Context Protocol — read-only by default, with message sending only through a token you explicitly mint with send access.

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.

Related MCP server: telegram-mcp

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:

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.

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.

• Node.js 22.22.3 or later; Node 22 and 24 LTS are tested.

• A Fenn account with Remote access: get the app 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.

Rotate, upgrade, uninstall

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:

• 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:

{ "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 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 and 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

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.

License

MIT