everos-mcp — Local EverOS MCP for Claude Code

A stdio MCP server that connects Claude Code to a self-hosted, local EverOS instance — so your coding assistant can search and save long-term memory without sending anything to the cloud.

Why this exists: EverMind's official evermem-claude-code and the third-party evermemos-mcp are both cloud clients — they require an EverMem API key and route data through EverMind's servers. If you run EverOS locally (your own keys, your own machine, data stays home), there was no ready-made MCP. This is it.

Features

• 4 tools: search_memory · remember · briefing · list_memories

• Auto project_id from cwd, matching ~/.claude/projects/<dir> encoding — so already-ingested conversations are findable

• Auto-starts EverOS via everos-up if it's down

• Data never leaves your machine

Related MCP server: CyberMem

Prerequisites

• A running local EverOS server at http://127.0.0.1:8000 (pip install everos && everos server start)

• Python 3.10+ and uv (or plain pip)

• Claude Code CLI

Install

git clone https://github.com/Marvisatron/everos-mcp.git ~/everos-mcp
cd ~/everos-mcp
uv venv .venv --python 3.14
uv pip install --python .venv/bin/python -e .

# self-check: remember a fact + search it back
.venv/bin/everos-mcp --smoke

Register with Claude Code

claude mcp add everos -s user \
  -e EVEROS_USER_ID="$USER" \
  -e EVEROS_APP_ID=claude-code \
  -e EVEROS_AGENT_ID=claude \
  -- "$HOME/everos-mcp/.venv/bin/everos-mcp"

claude mcp list   # → everos ... ✔ Connected

Restart Claude Code; the 4 tools are now available in every session.

Tools

Configuration (env)

How project_id works

EverOS scopes memory by project_id. This MCP derives it from the current working directory using Claude Code's own encoding (/Users/alice → -Users-alice, matching ~/.claude/projects/-Users-alice), so memories you ingested for that project are searchable without any config. Override with the project_id arg or EVEROS_PROJECT_ID.

Troubleshooting

• MCP not connected / tools missing — claude mcp list; ensure the binary path is absolute and exists; restart Claude Code.

• "EverOS not reachable" — start it (everos server start); with EVEROS_MCP_AUTOSTART=1 (default) the MCP auto-starts it via everos-up.

• Search finds nothing — check project_id matches the project you ingested into; ingest conversations first (e.g. via everos-ingest-claude or EverOS's /api/v1/memory/add).

• Transient 502 on search — handled internally (retry with backoff on 502/503/429). If EverOS's LLM provider is flaky under extraction load, wait and retry.

License

Apache-2.0. Built on top of the open-source EverMind-AI/EverOS.