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.
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.
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).
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
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.
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.
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.
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 (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.sqlite3Restore requires a new directory. Never copy a live database file without its WAL.
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 |
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.
Clear the thought history.
Returns:
dict: Status message
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose all behavioral traits. It only states the action and return type, omitting details like destructiveness, scope, or confirmation requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, front-loading the key action. While it lacks depth, it contains no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description is incomplete. It does not mention that clearing history is irreversible or provide any behavioral context, especially given the lack of annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description does not need to add parameter information since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Clear the thought history,' which matches the tool name 'clear_history.' The verb 'clear' and resource 'thought history' are clear and distinct from sibling tools like export_session or process_thought.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, side effects, or context for clearing history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the current thinking session to a file.
Args:
file_path: Path to save the exported session
Returns:
dict: Status message
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose side effects, file overwrite behavior, or access permissions; merely states the action and returns 'Status message' without detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus structured Args/Returns sections, clear and front-loaded; no unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool with one parameter and no output schema, but lacks information on file format, overwrite behavior, or status message contents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds 'Path to save the exported session' for file_path, clarifying its purpose beyond the schema's type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Export') and resource ('current thinking session') with destination ('to a file'), clearly distinguishing from siblings like import_session or generate_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; lacks context on prerequisites or situations like saving vs sharing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a summary of the entire thinking process.
Returns:
dict: Summary of the thinking process
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose behavioral traits (e.g., whether it is a read-only operation, requires state, or has side effects). It only states it returns a dict, which is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences, no unnecessary words, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and sibling tools, the description lacks details about what the summary contains, how it is generated, or any dependencies. It feels incomplete for a tool that produces a significant output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is trivially 100%. The description adds meaning by specifying the output is a summary of the thinking process, which is helpful beyond an empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Generate') and the resource ('summary of the entire thinking process'). It is a specific verb+resource combination that distinguishes it from sibling tools like 'clear_history', 'export_session', etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a thinking session from a file.
Args:
file_path: Path to the file to import
Returns:
dict: Status message
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It only states 'Import a thinking session from a file' without mentioning side effects (e.g., overwriting current session), file requirements, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (three lines) and uses a standard Args/Returns structure. However, it is too terse to be fully effective, lacking essential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description only vaguely states 'dict: Status message'. It does not explain what the status indicates or what happens to the existing session, leaving the agent uninformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It merely repeats 'Path to the file to import', adding no detail about file format, size limits, or path constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (import) and the object (thinking session from a file). It is distinguishable from sibling tools like export_session, but lacks specifics on file format or source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no context on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| tags | No | ||
| stage | Yes | ||
| thought | Yes | ||
| branch_id | No | ||
| axioms_used | No | ||
| is_revision | No | ||
| thought_number | Yes | ||
| total_thoughts | Yes | ||
| branch_from_thought | No | ||
| next_thought_needed | Yes | ||
| assumptions_challenged | No | ||
| revises_thought_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose all behavioral traits. It details what the tool does but omits side effects, permission requirements, error handling, or the state modifications (e.g., appending to a thought list). The return value is only vaguely described as 'dict: Analysis of the processed thought.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line summary, then structured as a docstring with Args and Returns. It is reasonably concise, though the parameter list is lengthy. Every sentence adds value, but could be more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, no output schema, no annotations), the description explains each parameter but lacks guidance on the overall workflow (e.g., sequential numbering, when to set 'next_thought_needed'). The stage values are enumerated, but the return value and error conditions are unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no property descriptions (0% coverage), so the description must compensate. The Args list provides brief explanations for each parameter, but these mostly restate the parameter names (e.g., 'thought: The content of the thought') without adding deeper semantics, constraints, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add a sequential thought with its metadata,' which clearly states the action and resource. This distinguishes it from sibling tools (clear_history, export_session, generate_summary, import_session) which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. The usage is implied by the tool name and sibling context, but no exclusion criteria or when-not scenarios are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1clear_historyexport_sessiongenerate_summaryimport_sessionprocess_thoughtScored 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.
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.
B2B, GovCon & LegalTech MCP server for live RFPs, contract parsing, compliance & proposal tools.
