Claude State MCP Server

Claude State MCP Server

SQLite-backed MCP server for Claude Code session persistence and multi-agent coordination.

Features

• Session Persistence — Save/restore session state across Claude Code restarts
• Event Logging — Track what you worked on, when
• Decision Tracking — Record architectural decisions with rationale
• File Locking — Prevent conflicts between parallel agents
• Agent Registry — See who's working on what
• Plan Tracking — Monitor GSD plan execution progress

Installation

# Clone or copy this directory
cd claude-state-mcp

# Install dependencies
npm install

# Build
npm run build

# Test it works
node dist/index.js
# Should see: "Claude State MCP initialized: ~/.claude/state.db"
# Ctrl+C to exit

Claude Code Configuration

Add to your ~/.claude/claude_desktop_config.json (or create it):

{
  "mcpServers": {
    "claude-state": {
      "command": "node",
      "args": ["/absolute/path/to/claude-state-mcp/dist/index.js"]
    }
  }
}

Or if you prefer npx (after publishing to npm):

{
  "mcpServers": {
    "claude-state": {
      "command": "npx",
      "args": ["claude-state-mcp"]
    }
  }
}

Database Location

Default: ~/.claude/state.db

Override with environment variable: ``bash CLAUDE_STATE_DB=/custom/path/state.db node dist/index.js ``

Available Tools

Session Management

| Tool | Description | |------|-------------| | session_start | Start a new session (call at beginning) | | session_end | End session with notes (call at end) | | session_get | Get last session for a branch | | session_list_active | List all active sessions | | session_update_progress | Update phase/plan/task progress | | session_history | "What did I work on last week?" |

Event Logging

| Tool | Description | |------|-------------| | event_log | Log an event (task completion, etc.) | | event_list | Get recent events |

Decision Tracking

| Tool | Description | |------|-------------| | decision_record | Record an architectural decision | | decision_list | Get all active decisions | | decision_supersede | Replace a decision with a new one |

File Coordination

| Tool | Description | |------|-------------| | files_lock | Lock files to prevent conflicts | | files_unlock | Release file locks | | files_check_conflicts | Check if files are locked | | files_list_locks | List all locks |

Agent Registry

| Tool | Description | |------|-------------| | agent_register | Register this Claude instance | | agent_heartbeat | Update heartbeat | | agent_list_active | List active agents | | agent_deregister | Mark agent as terminated |

Plan Tracking

| Tool | Description | |------|-------------| | plan_start | Record start of GSD plan | | plan_update_progress | Update task completion | | plan_complete | Record plan completion | | plan_status | Get status of plans in a phase |

Utility

| Tool | Description | |------|-------------| | query | Run custom SELECT query |

Usage Examples

Start of Session

Claude, start a session for branch feature/calendar in /Users/me/project

Claude calls: ``json { "tool": "session_start", "args": { "branch": "feature/calendar", "worktree_path": "/Users/me/project" } } ``

End of Session

Claude, save my session - we're stopping for the day

Claude calls: ``json { "tool": "session_end", "args": { "branch": "feature/calendar", "worktree_path": "/Users/me/project", "context_notes": ["Working on WeekView component", "Using react-big-calendar"], "next_steps": ["Finish time slot click handlers", "Add drag-and-drop"], "blockers": [], "uncommitted_files": ["src/components/WeekView.tsx"] } } ``

Check What's Running

What other Claude sessions are active?

Claude calls: ``json { "tool": "session_list_active" } ``

Query History

What did I work on last week?

Claude calls: ``json { "tool": "session_history", "args": { "days": 7 } } ``

Coordinate Files

Before editing a shared file:

{
  "tool": "files_check_conflicts",
  "args": {
    "files": ["src/lib/api.ts"],
    "project_path": "/Users/me/project",
    "worktree_path": "/Users/me/worktrees/feature-1"
  }
}

Integration with GSD Workflow

The /worktree-context command should call:

session_get(branch, worktree_path, include_events: true)
session_list_active()
files_list_locks(project_path)
agent_list_active()

The /persist-session command should call:

session_end(branch, worktree_path, context_notes, next_steps, blockers, uncommitted_files)

Schema

sessions        -- One active per branch/worktree
events          -- Activity log
decisions       -- Architectural decisions
file_locks      -- Coordination between agents
agents          -- Registry of Claude instances
plan_executions -- GSD plan tracking

Querying Directly

Use the query tool for custom queries:

{
  "tool": "query",
  "args": {
    "sql": "SELECT * FROM events WHERE event_type = 'task_completed' AND timestamp > datetime('now', '-1 day')"
  }
}

Or open the database directly:

sqlite3 ~/.claude/state.db