Skip to main content

MseeP.ai Security Assessment Badge Verified on MseeP

MCP Sequential Thinking

MCP Toplist Python Version License: MIT Code Style: Ruff

A local MCP server for working notes you can resume: evidence, decisions, risks and next actions for a difficult task, stored durably in SQLite and readable after any restart. It records what the caller writes; it does not generate, judge or improve reasoning, and it never asks for hidden chain-of-thought.

Sequential Thinking Server MCP server

Quick start

python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
python -m pip install -e .
python scripts/stdio_smoke.py                  # restart demo: write, restart, read back

Client configuration (Claude Desktop, Cursor, …):

{"mcpServers":{"working-notes":{
  "command":"/absolute/path/to/.venv/bin/mcp-sequential-thinking",
  "env":{"MCP_STORAGE_DIR":"/absolute/path/to/notes"}}}}

On Windows use .venv\Scripts\mcp-sequential-thinking.exe.

A typical session:

{"tool":"create_session","arguments":{"title":"Choose a local store","request_id":"create-1"}}
{"tool":"add_step","arguments":{"session_id":"<id>","content":"Two writers need unique positions.","kind":"evidence","request_id":"step-1"}}
{"tool":"add_step","arguments":{"session_id":"<id>","content":"Use SQLite.","kind":"decision","request_id":"step-2"}}
{"tool":"read_session","arguments":{"session_id":"<id>"}}

Lost the ID after a restart? list_sessions finds the session by title.

Tools

Tool Purpose
create_session Start a session from a title.
add_step Add a note; kind is note (default), observation, evidence, assumption, option, risk, decision or next_action.
list_sessions Find sessions by title or status.
read_session view="resume" (default): active notes, decisions first. view="steps": full history with filters.
finalize_session Store the caller's outcome and evidence IDs; no further steps afterwards.
delete_session Delete a session's database records (exports and backups remain).
export_session / import_session JSON archive of one session, confined to MCP_STORAGE_DIR/exports.

Links between notes. parent_step_id records provenance, supersedes_step_id replaces an earlier note (resume hides it, full history keeps it), and branch_from_step_id starts a named branch. All references stay inside one session.

Retries. Every write takes a request_id. Repeating a call with the same ID and input returns the original result; the same ID with different input returns IDEMPOTENCY_CONFLICT. finalize_session and delete_session also need expected_version.

Pagination and limits. Reads default to 20 entries and 12,000 characters (limit ≤ 100, max_chars 1,000–50,000). Follow cursor until it is null, and keep the same view while paging. truncated reports shortened content. A note too large for one response comes back as its first chunk; continue with step_id and content_offset until next_content_offset is null.

Errors set isError=true with a stable code and a short hint, e.g. INVALID_INPUT (with Fields: …), UNKNOWN_SESSION, INVALID_REFERENCE, CONFLICT (with current_version), SESSION_FINALIZED, IDEMPOTENCY_CONFLICT, STORAGE_BUSY (retry with the same request_id), PATH_OUTSIDE_EXPORTS, RESPONSE_LIMIT.

Sources attached to notes are caller-supplied and never fetched or verified.

Legacy tools (deprecated)

process_thought, generate_summary and clear_history, plus export_session / import_session without a session_id, work on a single shared legacy session. They remain for existing clients; every result carries a deprecation_notice. Use the session API for new work.

  • Stages: Problem Definition, Research, Analysis, Synthesis, Conclusion (case-insensitive). Order warnings are advisory unless --strict-stages is set.
  • main_line_progress counts mainline notes only, against your total_thoughts; it is not task completion.
  • Legacy import replaces the legacy history.
  • read_session(session_id="legacy") reads it; a legacy branch X appears as legacy-X there.

Storage and operation

mcp-sequential-thinking              # stdio server
mcp-sequential-thinking --health     # diagnostic check
mcp-sequential-thinking --ephemeral  # in memory only, lost on exit
  • Data lives in ~/.mcp_sequential_thinking (or MCP_STORAGE_DIR) as plaintext SQLite (WAL, synchronous FULL, 5 s busy timeout). Use a local disk; NFS/SMB and multiple hosts are not supported.
  • Several stdio servers may share one store. Local stdio trusts the OS user; a session ID is not authorization. HTTP/SSE are experimental.
  • Deletion is not secure erasure. There is no automatic retention.
  • On first start, an existing 0.6 JSONL history migrates into SQLite in one transaction, keeping IDs and content; a backup of the source stays in place. Stop old 0.6 servers first. Downgrading after new writes is not supported.

Backup and restore (all sessions, including retry keys):

python -m mcp_sequential_thinking.backup create  /path/to/storage /path/to/snapshot.sqlite3
python -m mcp_sequential_thinking.backup restore /path/to/NEW-storage /path/to/snapshot.sqlite3

Restore requires a new directory. Never copy a live database file without its WAL.

Tested with

Client OS Date
Python MCP SDK 2.0.0 and latest, Python 3.10–3.14 Linux, Windows every CI run
Claude Desktop Linux 2026-10-21

Development

uv run --extra dev ruff check .
uv run --extra dev ruff format --check .
uv run --extra dev mypy --strict mcp_sequential_thinking
uv run --extra dev pytest --cov=mcp_sequential_thinking --cov-fail-under=85
rm -rf dist && uv run --extra dev --with build --with twine --with jsonschema python scripts/check_artifacts.py

The artifact check builds and installs the wheel in isolation and runs a real restart round trip. Releases publish that tested artifact via Trusted Publishing once a GitHub release is created; the version lives in mcp_sequential_thinking/_version.py. See CHANGELOG.md for details.

Metadata

Release files for mcp-sequential-thinking 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-sequential-thinking 0.7.0
File Size Uploaded Provenance Actions
mcp_sequential_thinking-0.7.0.tar.gz 187.1 kB With provenance Details for mcp_sequential_thinking-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-sequential-thinking 0.7.0
File Interpreter ABI Platform Actions
mcp_sequential_thinking-0.7.0-py3-none-any.whl Python 3 none any Details for mcp_sequential_thinking-0.7.0-py3-none-any.whl

Total release size: 240.7 kB

Release files / mcp_sequential_thinking-0.7.0.tar.gz

Download URL mcp_sequential_thinking-0.7.0.tar.gz
Size 187.1 kB
Tags Source
SHA-256 checksum
How to use checksums
3c6275a3f0690fde48f160121bb1053bfc12626274e663a3eae5e2f634e09a4a
BLAKE2b-256 checksum
How to use checksums
29a62a3c56a0f141887fedcbe89edeb80d1a62d9cefa66b19a56bd6e7b7d7f69
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Release files / mcp_sequential_thinking-0.7.0-py3-none-any.whl

Download URL mcp_sequential_thinking-0.7.0-py3-none-any.whl
Size 53.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
315da432ad38574fc37e84cb02892dc8f1d63d94fdf1fd85e8bb3d2c37ac4fb0
BLAKE2b-256 checksum
How to use checksums
b6e52f6c2414d769e2c6a12bc6a534e84741dd6301af5affa47e4edc11d421ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Security for mcp-sequential-thinking 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_sequential_thinking-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page