Stateark logo

Stateark

Local-first MCP version control for saving, resuming, inspecting, and comparing AI project state.

Install Stateark

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "stateark": {
      "command": "npx",
      "args": [
        "-y",
        "stateark"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y stateark

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked .

Overview

The stateark MCP server saves AI project sessions as versioned local folders containing readable state files and project artifacts. It exposes savepoint, resume, history, and diff workflows through a local MCP agent, with optional Supabase mirroring. Use it when chats lose context or multiple local agents need a shared, versioned project state. Claude Desktop, Claude Code, and other local MCP hosts can connect, while hosted web clients cannot reach the default localhost service.

Use cases

  • Save project decisions between AI chats
  • Resume work with files and constraints intact
  • Compare project state across savepoints
  • Coordinate multiple local agents on one project store
  • Mirror selected savepoints to Supabase

Key features

  • Versioned local project savepoints
  • Resume, history, and diff workflows
  • Artifact carry-forward with SHA-256 manifests
  • Integrity warnings for incomplete file transfers
  • Serialized multi-process writes
  • Optional Supabase mirroring

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked

Recent health check succeeded.

11/11 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 7d ago via OSV.dev · stateark (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars2Stargazers on the source repository.
npm downloads268Package downloads in the last 30 days.
Last commit2mo agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Stateark works

What the stateark MCP server does

The stateark MCP server preserves the working state of an AI-assisted project between chats. Instead of retaining only a conversational summary, it stores decisions, requirements, constraints, relevant rejected approaches, open questions, and the files associated with a project. A savepoint creates a new version under the local StateArk directory, and a later resume loads the latest state into a new chat.

Savepoints are ordinary folders rather than a proprietary database. They include Markdown and JSON state files, metadata, a SHA-256 artifact manifest, journals, and the project files themselves. The local directory remains the source of truth, so the saved material stays usable in an editor even if the agent is no longer installed.

How it works

The local agent binds to 127.0.0.1 by default and exposes an MCP endpoint, an upload page, and a health endpoint. On first startup, it creates a random access key in the StateArk root. The MCP client uses the endpoint and key to communicate with the agent.

The main chat workflows are Savepoint, Resume, History, and Diff. Files omitted from a later savepoint can be carried forward with their original hash. StateArk also checks for likely incomplete transfers, including truncation markers, unexpectedly smaller files, described-but-missing files, and unchanged savepoints. These checks produce warnings without preventing a savepoint from being written.

A journal records turning points between savepoints for projects that already have a saved version. Writes are serialized across processes, allowing multiple agents on one machine to work against the same project store. A crashed process releases its lock automatically.

Setup and configuration

The simplest installation requires Node 20 or newer. Run npx stateark, then fully quit and reopen Claude Desktop. Source installation is also available through npm installation, the build step, and the setup script. npx stateark remove unregisters the service without deleting saved projects.

Local-only operation needs no .env file. The default store is ~/StateArk; STATEARK_LOCAL_ROOT can change it. Lock timing and file-system retry behavior can be adjusted with STATEARK_LOCK_WAIT_MS, STATEARK_LOCK_STALE_MS, and STATEARK_FS_RETRIES.

Optional Supabase mirroring requires the listed database migrations and SUPABASE_URL, SUPABASE_SECRET_KEY, STATEARK_OWNER_ID, and STATEARK_STORAGE_BUCKET. Local data is committed before a cloud push, and failed pushes can be retried with sync_savepoint. The mirror is not end-to-end encrypted.

Tools and capabilities

The stateark MCP server supports these project operations:

  • Save a new version of the current project state.
  • Resume the latest version in a fresh chat.
  • List project versions with History.
  • Compare savepoints with Diff.
  • Retry a failed Supabase mirror operation with sync_savepoint.
  • Preserve artifacts and verify their recorded SHA-256 hashes.
  • Record and consolidate journal entries.

Limitations and notes

StateArk is designed for local MCP clients. Claude Desktop, Claude Code, and similar local hosts can reach the default agent, but hosted Claude, ChatGPT, and Gemini web clients generally cannot connect to localhost. Remote access is not currently available; using an HTTPS route requires securing the access key, allowed hosts, and reverse proxy.

Multiple machines writing the same synced folder at once can create conflicts that Dropbox, OneDrive, or iCloud must resolve. The optional Supabase mirror is a hosted copy that can read stored content, not an end-to-end encrypted backup. The project is licensed under Elastic License 2.0, which does not allow offering it as a hosted or managed service to third parties.

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Stateark

stateark is an MCP server that connects local AI clients to a versioned project-state store on disk. Its main tools and workflows save session state, resume projects in new chats, list savepoints, compare versions, and retry optional Supabase synchronization. It also preserves artifacts, journals, metadata, and integrity information locally.

Run `npx stateark`, then completely quit and reopen Claude Desktop. StateArk registers its local agent and keeps savepoints under `~/StateArk` by default. Source installation uses `npm install`, `npm run build`, and `npm run setup`. Node 20 or newer is required.

Yes, stateark supports Claude Code as a local MCP host.

No, not directly from the default setup. Hosted web clients generally cannot reach the agent on your computer at localhost. Remote access is not currently available; exposing the service would require a secured HTTPS route and appropriate host and access-key configuration.

Run the three Supabase migrations, then set `SUPABASE_URL`, `SUPABASE_SECRET_KEY`, `STATEARK_OWNER_ID`, and `STATEARK_STORAGE_BUCKET`. Sync is optional and disabled when those settings are absent. Local data is written first, and failed pushes can be retried with `sync_savepoint`.

Related MCP servers

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewStateark AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/stateark?style=directory)](https://allmcps.com/mcp/stateark)
HTML Embed
<a href="https://allmcps.com/mcp/stateark"><img src="https://allmcps.com/api/badge/stateark?style=directory" alt="Stateark on AllMCPs" /></a>