Skip to main content
Glama
mfitzhenry

Claude State MCP Server

by mfitzhenry
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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

Related MCP server: swarm-mcp

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:

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:

{
  "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:

{
  "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:

{
  "tool": "session_list_active"
}

Query History

What did I work on last week?

Claude calls:

{
  "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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • swarm-mcp

    Volpestyle
    A
    license
    Not graded
    quality
    F
    maintenance
    MCP server that lets multiple coding-agent sessions on the same machine discover each other and collaborate through a shared SQLite database.
    20 npm
    1
    MIT

  • threadline-core

    richardoros
    A
    license
    A
    quality
    A
    maintenance
    MCP server providing structured continuity memory for AI coding agents, tracking decisions, open loops, and session state in local SQLite. Enables agents to resume work from verified state across sessions without replaying transcripts.
    17
    Apache 2.0
  • hive-memory by hivemem-dev

    hive-memoryofficial

    hivemem-dev
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server for personal and shared memory with full-text search (SQLite FTS5) and outcome tracking, compatible with any MCP agent like Claude Code, Cursor, and Codex CLI.
    6 npm
    MIT