Earkeep Download free

Connect Codex CLI to Earkeep

Last updated: · Reviewed quarterly

Earkeep runs a small MCP server so other tools on your machine can search and read your saved meetings. Codex CLI speaks the transport it uses directly, so connecting the two is a single command with no bridge in the middle. Once it is added, Codex can pull a meeting into whatever it is working on.

What you are connecting to

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. Reading meetings back and letting the model work through them is how you get at what was actually said.

Set it up

Run this in your terminal, with Earkeep running:

shell 
codex mcp add earkeep --url http://127.0.0.1:8730/mcp

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.

Using Codex inside an editor? The IDE extension shares this same configuration, so adding it here is usually enough. If you would rather edit the file directly, that route is on connect Codex in your IDE.

Check it works

List what Codex knows about:

shell 
codex mcp list

Then ask for something only Earkeep can answer:

"Use the earkeep tools to list my most recent meetings, then read the latest one and turn the decisions into a checklist."

Real titles from your own week mean the connection is live.

If something goes wrong

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.

The port is wrong. Open Settings → General in Earkeep 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:

shell 
codex mcp remove earkeep

Related

Frequently asked questions

Do I need this if I already run Codex inside Earkeep?

No. An agent started from Earkeep's own panel already has the meeting in hand, and the MCP server is wired into that session automatically. This page is for the other direction: Codex in your terminal, reaching back into your meeting history.

Can it change or delete my meetings?

No. The server is read-only. It can search meetings and read them, and there is no tool for anything else.

Does this send my transcripts to OpenAI?

Earkeep's side stays on your device: the server listens on loopback and nothing leaves the machine through it. What happens next is Codex's business, and it calls its model provider's API, so a transcript you ask it to read is a transcript you have sent to that provider.

Why can't it search what was said inside a meeting?

The server searches span metadata, meaning titles and notes. Transcripts are plain files on your own disk, so searching their contents is what grep is for, or you can have the agent read meetings back and search them itself.

Does the server need an account or an API key?

No. It listens on your own machine and has nothing to authenticate against.

Your meetings, where you already work

Download free for macOSAll how-tos

14-day full trial, no account required.