DeerDawn MCP Server

Never start cold. Every new AI session opens already briefed on your project.

DeerDawn is AI session memory — your AI's chief of staff — for Claude Code, Claude.ai, Claude Desktop, ChatGPT, Cursor, Windsurf, VS Code, Zed, Codex, and any other MCP-compatible agent. Start a session anywhere and start_session hands the agent the brief: what you were working on, what was decided, and what's blocking — so no session starts cold.

About this repository. DeerDawn is a hosted service. This repo holds the public install guide, the server.json manifest published to the MCP registry, and a Dockerfile that launches the published npm package. The server itself ships from npm as @deerdawn/mcp-server; its source is not open. Issues and questions are welcome here.

Quick start — hosted server (recommended, no install)

Connect to the hosted MCP endpoint. No API key needed — you sign in with your browser the first time a DeerDawn tool is called.

Claude Code

claude mcp add -s user --transport http deerdawn https://api.deerdawn.com/api/v1/mcp

Every other tool — add a remote MCP server (sometimes called a connector) with this URL:

https://api.deerdawn.com/api/v1/mcp

Leave any OAuth client fields blank. Click Connect (or restart the tool) and sign in when the DeerDawn tab opens. If your tool connects without prompting for sign-in, the first DeerDawn tool call returns the sign-in URL — open it, sign in once, and retry the call; setup completes automatically.

Then say: "Start a DeerDawn session."

The hosted server exposes 18 core session-memory tools. For repo-file writes, automatic capture hooks, and the full 35-tool set, use the local install below.

Local install (stdio) — optional upgrade

Run the server on your machine via npx -y @deerdawn/mcp-server@latest when you want deeper integration:

• Writes .deerdawn-context.md / .cursorrules into your repo so context loads with no tool call.
• Installs SessionStart / Stop hooks that capture and flush context automatically.
• Exposes the full set of 35 tools (the hosted server exposes 18 core ones).

Sign-in works the same way — browser OAuth by default, no API key required. On first run without credentials, the server starts a device-flow sign-in: the URL is printed to stderr, saved to ~/.deerdawn/pending-auth.json, and returned in-band by the get_auth_status tool (use that in GUI hosts where stderr isn't visible). After you approve in the browser, credentials are saved to ~/.deerdawn/credentials.json and every future session is authenticated.

Prefer non-interactive auth (CI, headless, SSH)? Create a key at app.deerdawn.com → Settings → API Keys (it starts with dd_) and set DEERDAWN_API_KEY in the config's env block — browser sign-in is then skipped entirely.

Claude Code (CLI)

Run the setup command — it registers the server, signs you in, and configures hooks in one step:

npx -y @deerdawn/mcp-server@latest setup

Or register manually (user scope so it works across all projects):

claude mcp add -s user deerdawn -e DEERDAWN_API_URL=https://api.deerdawn.com -e DEERDAWN_SURFACE_ID=claude_code -- npx -y @deerdawn/mcp-server@latest

Restart Claude Code after registering. If you haven't signed in yet, call get_auth_status — it returns the browser URL to complete sign-in.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json (same path on macOS, Linux, and Windows):

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  }
}

Windsurf

macOS: ~/.codeium/windsurf/mcp_config.json Windows: %APPDATA%\Codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  }
}

VS Code (GitHub Copilot / Continue)

Add to .vscode/settings.json or user settings.json:

{
  "mcp": {
    "servers": {
      "deerdawn": {
        "command": "npx",
        "args": ["-y", "@deerdawn/mcp-server@latest"],
        "env": {
          "DEERDAWN_API_URL": "https://api.deerdawn.com"
        }
      }
    }
  }
}

For Continue (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "deerdawn",
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  ]
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "deerdawn": {
      "command": {
        "path": "npx",
        "args": ["-y", "@deerdawn/mcp-server@latest"],
        "env": {
          "DEERDAWN_API_URL": "https://api.deerdawn.com"
        }
      }
    }
  }
}

Codex (OpenAI)

Add to ~/.codex/config.toml:

[mcp_servers.deerdawn]
command = "npx"
args = ["-y", "@deerdawn/mcp-server@latest"]
startup_timeout_sec = 120

[mcp_servers.deerdawn.env]
DEERDAWN_API_URL = "https://api.deerdawn.com"

To skip browser sign-in in any of these configs, add "DEERDAWN_API_KEY": "dd_your_key_here" to the env block (Codex TOML: DEERDAWN_API_KEY = "dd_your_key_here" under [mcp_servers.deerdawn.env]).

Host naming note

Some MCP hosts expose tools with a server prefix (for example deerdawn-get_auth_status) instead of bare names (get_auth_status). If a tool name is not found, retry with the deerdawn- prefixed variant.

Environment variables

All optional. With no env vars at all, the server starts and walks you through browser sign-in.

Session memory tools

The local server exposes 35 tools (the hosted remote exposes 18 core ones). These are the ones to reach for in every session.

start_session

Call this at the start of every session. Returns the active project context for the current directory plus a compact map of all other projects — one API call, ~100–180 tokens total. Do not call list_context_map + get_context separately; this replaces both.

update_context

Push a context update. Call this whenever: a decision is made, the current task changes, a blocker is found, or meaningful progress happens. Don't wait until the end of the session — updates are cheap and keep the brief every new session reads current.

project_id: "proj-abc123"
summary: "Switched auth from JWT to session tokens — JWT had XSS risk via localStorage. Now using Redis-backed sessions."

get_context

Get project context by section. Defaults to [task, status] (~30 tokens). Pass sections=["all"] for everything.

project_id: "proj-abc123"
sections: ["task", "decisions", "blocking"]

import_local_context

Import context from CLAUDE.md, AGENTS.md, or .cursorrules in the current directory. Call without confirmed: true first — it shows a free preview of what would be imported. Then call again with confirmed: true to commit.

complete_setup

One-call setup fallback for brittle hosts: checks auth status, applies local setup for a surface, and runs import_local_context preview + confirmation if local files are found.

Example:

complete_setup
{
  "surface": "cursor"
}

cleanup_context

Clean up task state at handoff or finish time. Use this to mark the active task complete and clear open-task command history so the next agent sees clean state.

When the task is clearly done and there are no unresolved questions, call this automatically with complete_task=true (no extra confirmation loop).

cleanup_context
{
  "complete_task": true
}

search_context

Search across all projects. Examples: "decisions about authentication", "projects using PostgreSQL", "what's blocking the billing work".

list_projects

List all projects with IDs and last-updated timestamps. Use this when you explicitly need a project index. For normal startup, prefer start_session.

create_project

Create a new project when starting something that has no existing project entry.

Workspace knowledge tools

get_workspace_overview

Use mode=startup at the start of a session for a compact orientation brief. Use mode=overview when the user asks "what am I working on?" or wants a broader picture.

Read the full README on GitHub →