@everstateai/mcp

Everstate MCP Server - Persistent memory for AI coding assistants.

Installation

Option 1: Global Install (Recommended)

npm install -g @everstateai/mcp

Option 2: Use npx

No installation needed - just reference in your MCP config (see below).

Configuration

Claude Code / VS Code

Add to your MCP configuration:

Global (~/.claude.json):

{
  "mcpServers": {
    "everstate": {
      "command": "npx",
      "args": ["-y", "@everstateai/mcp"],
      "env": {
        "EVERSTATE_API_KEY": "ck_your_api_key_here"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "everstate": {
      "command": "everstate-mcp",
      "env": {
        "EVERSTATE_API_KEY": "ck_your_api_key_here"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "everstate": {
      "command": "npx",
      "args": ["-y", "@everstateai/mcp"],
      "env": {
        "EVERSTATE_API_KEY": "ck_your_api_key_here"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "everstate": {
      "command": "npx",
      "args": ["-y", "@everstateai/mcp"],
      "env": {
        "EVERSTATE_API_KEY": "ck_your_api_key_here"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "everstate": {
      "command": "npx",
      "args": ["-y", "@everstateai/mcp"],
      "env": {
        "EVERSTATE_API_KEY": "ck_your_api_key_here"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | EVERSTATE_API_KEY | Yes | Your Everstate API key (get one at everstate.ai) | | EVERSTATE_PROJECT_ID | No | Explicit project ID (auto-detected from .everstate.json if not set) | | EVERSTATE_API_URL | No | API base URL (default: https://www.everstate.ai) | | EVERSTATE_MODE | No | Tool mode: core, meta, or extended |

Project Detection

The MCP proxy automatically detects your project in this order:

1. EVERSTATE_PROJECT_ID env var - Explicit configuration wins
2. .everstate.json file - Searches current directory and parents for a config file with projectId
3. API fallback - Fetches your projects and uses the first one

For multi-project setups, create a .everstate.json in each project:

{
  "projectId": "proj_abc123...",
  "projectName": "My Project"
}

Quick Setup

The easiest way to set up Everstate:

npx @everstateai/mcp setup ck_YOUR_API_KEY

Setup automatically detects which AI tools you have installed and configures all of them:

• Detects Claude Code, Claude Desktop, Cursor, and Windsurf
• Configures MCP settings for each detected tool
• Creates .everstate.json in your project
• Sets up session hooks
• Stores your API key securely (~/.everstate/api-key)

Options:

npx @everstateai/mcp setup --help                       # Show all options
npx @everstateai/mcp setup KEY -e cursor                # Only configure Cursor
npx @everstateai/mcp setup KEY -y                       # Non-interactive (skip prompts)
npx @everstateai/mcp setup KEY --project-dir /path      # Specify project directory
npx @everstateai/mcp setup KEY --skip-hooks             # Skip hook installation
npx @everstateai/mcp setup KEY --force                  # Clean reinstall
npx @everstateai/mcp setup KEY --upgrade                # Upgrade existing installation

CLI Commands

These commands work in any terminal, even when MCP tools aren't available:

npx @everstateai/mcp recall "search query"     # Search your project memory
npx @everstateai/mcp sync                      # Load project context
npx @everstateai/mcp status                    # Show project status
npx @everstateai/mcp done -s "what happened"   # End session with summary
npx @everstateai/mcp update-all                # Update all projects at once
npx @everstateai/mcp update-all --scan /path   # Scan specific directory
npx @everstateai/mcp doctor                    # Diagnose installation issues
npx @everstateai/mcp repair                    # Auto-fix common issues
npx @everstateai/mcp --version                 # Check installed version

How It Works

This proxy is intentionally minimal. It:

1. On startup: Auto-detects your project from .everstate.json or API
2. Auto-session: First tool call auto-starts a session (no explicit sync() needed)
3. On tool list: Fetches tool definitions from the Everstate API (5 core tools by default)
4. On tool call: Forwards the call to the Everstate API with your projectId
5. Returns: Responses to Claude/Cursor/etc.

All business logic, tool schemas, and data operations live server-side. Benefits:

• Instant updates - New features without npm updates
• Feature gating - Tools enabled by your API key tier
• Security - All authentication and metering server-side
• Auto-session detection - Proxy tracks idle time, auto-syncs after 5 minutes of inactivity

Core Tools (5)

| Tool | Purpose | |------|---------| | sync | Start session, load context (auto-called) | | done | End session with summary (auto-called on session end) | | recall | Search past sessions, decisions, gotchas | | log | Record progress, decisions, gotchas, blockers | | everstate | Meta-tool for 100+ actions via namespace.action |

Automatic Features

These work via hooks installed during setup:

| Feature | Hook | Description | |---------|------|-------------| | Auto-progress | PostToolUse (Edit/Write/Bash) | File edits and commands logged automatically | | Gotcha warnings | PreToolUse (Edit/Write) | Relevant gotchas surface before editing flagged files | | Task sync | PostToolUse (TodoWrite) | TodoWrite list syncs with dashboard | | Auto-done | Stop/SessionEnd | Session auto-saved when conversation ends |

Troubleshooting

"No such tool available"

1. Restart your AI tool (Claude Code, Cursor, etc.)
2. Check your API key is correct
3. Verify the MCP config JSON is valid

Tools fail with "projectId is required"

1. Create .everstate.json in your project directory
2. Or set EVERSTATE_PROJECT_ID in your MCP config
3. Or call sync({ projectId: "proj_..." }) at session start

Multiple projects

Use .everstate.json in each project directory. The proxy auto-detects based on your working directory.

Get an API Key

1. Go to everstate.ai
2. Sign up (free)
3. Generate an API key from the dashboard

License

MIT