Sequential Thinking MCP Server
It is a local MCP server for durable sequential-thinking/working notes that can be resumed after restarts.
Create, list, read/resume, finalize, and delete sessions.
Add steps/notes with kinds such as evidence, assumption, option, risk, decision, and next action.
Track provenance, supersession, and branches between notes.
Export/import a session as a JSON archive.
Use retries/idempotency, pagination, content chunking, version checks, and stable errors.
Run via stdio, health-check, or ephemeral mode; store in SQLite, migrate old history, and back up/restore.
Use legacy tools to add sequential thoughts, generate summaries, clear history, and export/import legacy sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Sequential Thinking MCP Server help me plan a marketing campaign for our new product launch"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Sequential Thinking
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.
Installation
Published on PyPI and in the
MCP Registry as
io.github.arben-adm/mcp-sequential-thinking. With uv
installed, uvx mcp-sequential-thinking runs it without a manual install
(pin with uvx mcp-sequential-thinking@0.7.0). MCP_STORAGE_DIR is optional.
Claude Code
claude mcp add working-notes -- uvx mcp-sequential-thinking # this project only
claude mcp add --scope user working-notes -- uvx mcp-sequential-thinking # all projects
claude mcp add --scope project working-notes -- uvx mcp-sequential-thinking # shared via .mcp.jsonGemini CLI
gemini mcp add working-notes uvx mcp-sequential-thinking # writes .gemini/settings.jsonCodex CLI
codex mcp add working-notes -- uvx mcp-sequential-thinkingClaude Desktop (Settings → Developer → Edit Config, claude_desktop_config.json)
{"mcpServers":{"working-notes":{
"command":"uvx",
"args":["mcp-sequential-thinking"],
"env":{"MCP_STORAGE_DIR":"/absolute/path/to/notes"}}}}Restart Claude Desktop afterwards.
VS Code (.vscode/mcp.json)
{"servers":{"working-notes":{"type":"stdio","command":"uvx","args":["mcp-sequential-thinking"]}}}If a GUI client cannot find uvx, use its absolute path (which uvx).
From source
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 backThen point the client at /absolute/path/to/.venv/bin/mcp-sequential-thinking
(Windows: .venv\Scripts\mcp-sequential-thinking.exe) instead of uvx.
Related MCP server: Sequential Thinking MCP Server
Quick start
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 |
| Start a session from a title. |
| Add a note; |
| Find sessions by title or status. |
|
|
| Store the caller's outcome and evidence IDs; no further steps afterwards. |
| Delete a session's database records (exports and backups remain). |
| JSON archive of one session, confined to |
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-stagesis set.main_line_progresscounts mainline notes only, against yourtotal_thoughts; it is not task completion.Legacy import replaces the legacy history.
read_session(session_id="legacy")reads it; a legacy branchXappears aslegacy-Xthere.
Storage and operation
mcp-sequential-thinking # stdio server
mcp-sequential-thinking --health # diagnostic check
mcp-sequential-thinking --ephemeral # in memory only, lost on exitData lives in
~/.mcp_sequential_thinking(orMCP_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.sqlite3Restore 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.pyThe 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.
Available Tools
5 toolsclear_historyB
Clear the thought history.
Returns:
dict: Status message
Inputs: no named parameters.
export_sessionB
Export the current thinking session to a file.
Args:
file_path: Path to save the exported session
Returns:
dict: Status message
Inputs: file_path (required).
generate_summaryB
Generate a summary of the entire thinking process.
Returns:
dict: Summary of the thinking process
Inputs: no named parameters.
import_sessionC
Import a thinking session from a file.
Args:
file_path: Path to the file to import
Returns:
dict: Status message
Inputs: file_path (required).
process_thoughtB
Add a sequential thought with its metadata.
Args:
thought: The content of the thought
thought_number: The sequence number of this thought
total_thoughts: The total expected thoughts in the sequence
next_thought_needed: Whether more thoughts are needed after this one
stage: The thinking stage (Problem Definition, Research, Analysis, Synthesis, Conclusion)
tags: Optional keywords or categories for the thought
axioms_used: Optional list of principles or axioms used in this thought
assumptions_challenged: Optional list of assumptions challenged by this thought
is_revision: Whether this thought revises an earlier thought
revises_thought_number: The number of the earlier thought being revised (required if is_revision is true)
branch_from_thought: The thought number this thought branches from, to explore an alternative path
branch_id: Identifier for the branch (letters, digits, '-', '_'; max 64 chars; requires branch_from_thought)
ctx: Optional MCP context object
Returns:
dict: Analysis of the processed thought
Inputs: stage (required), thought (required), thought_number (required), total_thoughts (required), +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct purpose: clearing history, exporting/importing sessions, generating summaries, and processing thoughts. No functional overlap.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., clear_history, export_session). The naming is predictable and clear.
Five tools is appropriate for a focused sequential thinking server, covering core operations without unnecessary bloat.
The tool surface covers the full lifecycle: adding thoughts (with revision and branching), clearing, exporting/importing, and generating summaries. Minor gap: lack of a dedicated edit/delete tool, but revisions handle edits.
Maintenance
Related MCP Connectors
An MCP server for deep research or task groups
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
MCP server for generating rough-draft project plans from natural-language prompts.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseBqualityAmaintenanceAn adaptation of the MCP Sequential Thinking Server designed to guide tool usage in problem-solving. This server helps break down complex problems into manageable steps and provides recommendations for which MCP tools would be most effective at each stage.3399 npm588MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables Claude to break down complex problems into manageable steps with support for revision and branching, facilitating dynamic and reflective problem-solving through a structured thinking process.17 npmMIT
- AlicenseAqualityDmaintenanceA MCP server that implements sequential thinking protocols, provides structured problem-solving methods, decomposes complex problems into manageable steps, and supports iterative optimization and alternative reasoning paths.12Apache 2.0
- AlicenseAqualityDmaintenanceA structured problem-solving MCP server that breaks down complex tasks into sequential steps, supports iterative refinement and branching, and helps maintain context and explore alternative reasoning paths.111 npm41MIT