mcp-sequential-thinking: a schema-validated thinking journal for MCP clients
Local MCP work notes with persistent sessions, decisions, evidence and resumable tasks.
At a glance
- What is it?
- This Python MCP server records an agent's reasoning as typed, append-only notes with stages, revisions and branches. It stores and structures the process; it does not improve the reasoning, and the README says so directly.
- Who is it for?
- Adopt it if you need a durable, inspectable record of an MCP client's reasoning across sessions and you accept that the server only records, never evaluates. Skip it if you want the server to critique or improve reasoning, or if you cannot tolerate a single append-only JSONL file as the store.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap it fills: reasoning that survives the context window
Most MCP thinking tools are stateless helpers. The model emits a thought, the tool echoes it back, and when the session ends the reasoning is gone. This server takes the opposite position: thoughts are records, written to an append-only JSONL session log with thread-safe file access and what the README calls automatic crash recovery. The intended user is an engineer or analyst running a long task through an MCP client who later needs to answer questions like which assumptions were challenged, which branches were left open, and what the conclusion actually rested on. The README is unusually blunt about scope: the server "does not evaluate, generate, or improve the reasoning itself; that stays with whatever model is calling it." That sentence is the whole design contract. If you want a thinking partner, this is the wrong repository. If you want a ledger, it is the right one.
Stages, revisions and branches as first-class records
The mechanism is a fixed set of cognitive stages: Problem Definition, Research, Analysis, Synthesis, Conclusion. Every recorded thought is tagged with a stage, and the server warns when a thought skips ahead or backtracks. In --strict-stages mode those warnings become rejections, which means the mode is a behavioural constraint on the calling model, not a lint you can ignore. Revisions let a later thought amend an earlier one, and branching lets the caller fork an alternative line of reasoning. Both are tracked, and the analysis layer is revision-aware and branch-aware, so a summary can show a revision chain rather than a flat list. Progress reporting avoids the usual single percentage: the README describes an explicit mainline position, total recorded thoughts, branch count and revision count. That is a more honest shape for a process that forks. Note what the related-thought analysis actually is: lexical similarity plus a separate same-tag, same-stage grouping. The README labels it "a categorical signal, not a claim of semantic relevance." Good. Anyone who has watched an embedding-based similarity score mislead a retrieval pipeline will appreciate the restraint.
Running it: uvx, pip, or a clone
The shortest path is uvx, which fetches from PyPI and runs without an install step: uvx mcp-sequential-thinking. For a permanent install, pip install mcp-sequential-thinking followed by mcp-sequential-thinking. Python 3.10 or higher is required, and the README lists UV as a prerequisite. For client wiring, the Claude Desktop config lives at ~/.config/Claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, and %APPDATA%\Claude\claude_desktop_config.json on Windows. The recommended entry is the uvx form, with command set to uvx and args set to ["mcp-sequential-thinking"]. To run unreleased code, the README shows pointing uvx at the repository with --from git+https://github.com/arben-adm/mcp-sequential-thinking. If you installed the package, the entry point is simply mcp-sequential-thinking. For source work: uv venv, activate, uv pip install -e ".[dev]" for testing tools or ".[all]" for everything optional, then uv run -m mcp_sequential_thinking.server. Tests run with pytest, and pytest --cov=mcp_sequential_thinking adds coverage. The repository ships a debug_mcp_connection.py utility for diagnosing connections, which is a small but telling inclusion: MCP wiring fails often enough that the author kept a dedicated script.
Storage, thread safety and the append-only trade-off
Persistence is a single append-only JSONL file guarded by portalocker for thread-safe access, with storage_utils.py holding shared storage operations. Append-only is the right call for an audit trail: you cannot silently overwrite a thought, and crash recovery is a matter of reading what was written. It is also the main operational constraint. There is no database, no index and no compaction mentioned in the README, so long-running sessions grow the file linearly and every read walks it. The README does list import and export for sharing and reusing sessions, which mitigates this somewhat, but nothing in the supplied material describes retention policy, rotation, or a size ceiling. If you are running many long sessions, that is the first thing to measure before committing. The error model is worth noting because it is more careful than most: protocol and validation errors (a bad stage, a duplicate thought number, path traversal) fail the call outright, while execution errors the caller can adapt to come back as an ordinary tool result. That split lets a model distinguish "you sent something invalid" from "something went wrong downstream," which is exactly the distinction a retry loop needs.
Where it stops being the right tool
The server records; it does not reason. A model that produces shallow thoughts will produce a beautifully structured, schema-validated record of shallow thoughts. Nothing in the pipeline catches a wrong conclusion, and the summary generation is described as deterministic extraction of what was recorded, not new reasoning. So the summary can tell you that three assumptions were challenged and two branches remain open; it cannot tell you whether the surviving branch is sound. The strict stage mode is a second boundary. It is a constraint on sequence, not on quality: a thought can satisfy the stage order and still be empty. And the lexical related-thought analysis will miss conceptual connections that share no vocabulary, which the README effectively concedes by calling it categorical rather than semantic. Finally, the supplied material does not describe authentication, multi-user access, or any network transport beyond the local MCP server pattern, so treating this as a shared team service is not supported by anything documented here.
How it differs from a plain note-taking MCP server
The obvious alternative is a generic notes or memory MCP server: append text to a file or a vector store, retrieve it later. The difference is schema. A notes server accepts arbitrary text and gives you back arbitrary text. This project constrains each entry to a stage, a thought number, a revision or branch relationship, and a Pydantic-validated shape, then derives progress, summaries and related-thought groupings from that structure. You get less freedom and more queryable structure. The cost is real: a freeform note can hold a half-formed intuition that fits no stage, and here that either trips a warning or, under --strict-stages, gets rejected. The benefit is that the record can be summarized deterministically per stage, with revision chains and open branches surfaced rather than reconstructed by hand. If your workflow is exploratory and messy, a plain notes server will fit better. If you need to hand someone a structured account of how a decision was reached, the schema is the point.
Maintenance, licence and what to check first
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are retained. That is a permissive baseline, not legal advice; if you are redistributing it inside a product, read LICENSE and your own obligations. Maintenance signals in the supplied material: releases v0.6.0 in July 2026 and v0.6.1 in August 2026, with the last push to master in September 2026. That is a steady cadence on a pre-1.0 version, so expect interface changes between minor releases. The dependency surface is modest (Pydantic, portalocker, MCP Python SDK 2.x), and the README states mypy --strict is clean with declared output schemas for every tool, which lowers the cost of reading the code when something breaks. Two things to verify before adopting: the exact on-disk location and naming of the JSONL session file, since nothing in the supplied material specifies it, and whether your client's MCP SDK version matches the 2.x line the README names. The repository includes tests for analysis, models and storage, so pytest is the fastest way to confirm the package behaves as documented on your Python version.
Editorial conclusion
Adopt it if you need a durable, inspectable record of an MCP client's reasoning across sessions and you accept that the server only records, never evaluates. Skip it if you want the server to critique or improve reasoning, or if you cannot tolerate a single append-only JSONL file as the store. Before wiring it into a client, verify the --strict-stages behaviour against your actual prompts, confirm where the session file lands on disk, and check that your MCP Python SDK version matches the 2.x dependency the README names.
Community notes