Claude State MCP Server
Provides a query tool for running custom SELECT queries against the SQLite database that stores session and event data.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 exitClaude 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.jsAvailable Tools
Session Management
Tool | Description |
| Start a new session (call at beginning) |
| End session with notes (call at end) |
| Get last session for a branch |
| List all active sessions |
| Update phase/plan/task progress |
| "What did I work on last week?" |
Event Logging
Tool | Description |
| Log an event (task completion, etc.) |
| Get recent events |
Decision Tracking
Tool | Description |
| Record an architectural decision |
| Get all active decisions |
| Replace a decision with a new one |
File Coordination
Tool | Description |
| Lock files to prevent conflicts |
| Release file locks |
| Check if files are locked |
| List all locks |
Agent Registry
Tool | Description |
| Register this Claude instance |
| Update heartbeat |
| List active agents |
| Mark agent as terminated |
Plan Tracking
Tool | Description |
| Record start of GSD plan |
| Update task completion |
| Record plan completion |
| Get status of plans in a phase |
Utility
Tool | Description |
| Run custom SELECT query |
Usage Examples
Start of Session
Claude, start a session for branch feature/calendar in /Users/me/projectClaude 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 dayClaude 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 trackingQuerying 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.dbTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Remote MCP server for notes, tasks, kanban boards and docs - the Slates agentic workspace
1Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server that enables multiple Claude agents to coordinate through a shared message bus with SQLite persistence and real-time clock anchoring.MIT
- AlicenseNot gradedqualityBmaintenanceMCP server that lets multiple coding-agent sessions on the same machine discover each other and collaborate through a shared SQLite database.29 npm1MIT
- AlicenseAqualityCmaintenanceMCP 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.17Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA local-first MCP server providing persistent, layered memory (episodic, semantic, procedural, resource) for AI agents, with search, versioning, and session management via a single SQLite file.78 npm3MIT