Skip to main content
Glama
Sequential Thinking MCP Server

Sequential Thinking MCP Server

by arben-adm

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.

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.json

Gemini CLI

gemini mcp add working-notes uvx mcp-sequential-thinking   # writes .gemini/settings.json

Codex CLI

codex mcp add working-notes -- uvx mcp-sequential-thinking

Claude 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 back

Then 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

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.

Available Tools

5 tools
clear_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

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a distinct purpose: clearing history, exporting/importing sessions, generating summaries, and processing thoughts. No functional overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., clear_history, export_session). The naming is predictable and clear.

    Tool Count5/5

    Five tools is appropriate for a focused sequential thinking server, covering core operations without unnecessary bloat.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      An 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.
      3
      399 npm
      588
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      1
      7 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      1
      2
      Apache 2.0