Skip to main content
Glama
mfitzhenry

Claude State MCP Server

by mfitzhenry
OverviewSchemaRelated ServersScoreDiscussions
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: claude-sync

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 installed

F
license - not found
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mfitzhenry/claude-state-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server