Connect Claude Code to Earkeep

The server is always on while Earkeep is running, and it listens on 127.0.0.1 and nothing else. That loopback binding is the security model: 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.

Run this in your terminal, with Earkeep running:

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

If you changed the port. The address above is the default. Earkeep shows its real one: press MCP at the bottom of the left rail, and the Connect apps panel gives you the address and this same command with the right port already in it, 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 connection fails or the tools don't appear. Earkeep has to be running: the server lives inside the app, so a closed app is a closed port. Check the app is open, then check the address matches the one in the Connect apps panel.

The port is wrong. If another application was already using the default port when Earkeep started, Earkeep's own setting is the one to trust. Open Settings → General to see or change the MCP server port. A 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.