Connect Claude Code to Earkeep

Every time Earkeep opens, it puts the command at ~/.local/bin/earkeep-mcp, pointing into the app. Claude Code launches it when it needs it and talks to it over standard input and output. The command reads your transcript files straight from disk, so it works whether or not Earkeep is running, and it opens no port: there is no address at which anything off your device could reach it.

It offers two tools, and both are read-only. Nothing connected here can create, edit or delete a meeting.

• search_spans finds saved meetings by a case-insensitive match on their title or notes, or lists all of them when you don't give it a query. Newest first, twenty at a time.
• read_span takes one meeting's id and returns that meeting plus the transcript lines it covers.

Worth knowing before you write a prompt: search matches titles and notes, not the words inside transcripts. So "find the meeting about pricing" works when the meeting is called that, and the way to search the actual conversation is to read the meetings back and let the model do it, or to grep the files on disk yourself.

Open Earkeep once, so the command is in place, then run this in your terminal:

That adds it for the current project. Add --scope user to make it available in every project instead:

Or over HTTP. Earkeep also serves the same tools at a loopback address while the app is running. Use this instead if you would rather connect by URL:

The address above is the default port. Settings → MCP in Earkeep shows its real one, and both commands with your own path and port already in them, ready to copy.

1. Confirm the server is registered:

Then ask Claude Code for something only Earkeep can answer. Anything that requires it to go looking will do:

"Use the earkeep tools to list my most recent meetings, then read the latest one and summarise what was decided."

If it comes back with real meeting titles from your own week, the connection is live.

The server fails to start or the tools don't appear. The command is probably missing. Check it is there:

If nothing is there, open Earkeep once and it puts the command in place. If something else is at that path, Earkeep leaves it alone rather than overwrite a file you put there; move it aside and open Earkeep again, or add the app directly with claude mcp add earkeep -- /Applications/Earkeep.app/Contents/MacOS/earkeep mcp.

You connected over HTTP and it fails. That route needs Earkeep running, because the HTTP server lives inside the app. Check the port too: Settings → MCP is the one to trust. A port change takes effect when you restart Earkeep, and you will need to re-add the server with the new address.

It connects but finds nothing. The server searches saved meetings. A day that was captured but never had a span kept from it has nothing to find, so keep a meeting first and try again.

You want it gone. Remove it the way you added it:

• Set up Claude Code as an in-app agent: the other direction, where Claude Code runs inside Earkeep beside the meeting and needs no MCP setup at all.
• Agents and MCP: why both exist and what each is for.
• Local RAG: querying your meeting history when you want more than metadata search.
• All Earkeep how-tos.