Skip to content
Back to search

mcp-sequential-thinking

Local MCP work notes with persistent sessions, decisions, evidence and resumable tasks.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/arben-adm--mcp-sequential-thinking/badge.svg)](/listings/arben-adm--mcp-sequential-thinking)

HTML

<a href="/listings/arben-adm--mcp-sequential-thinking"><img src="/api/listings/arben-adm--mcp-sequential-thinking/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The package is published on PyPI as [`mcp-sequential-thinking`](https://pypi.org/project/mcp-sequential-thinking/). The easiest way to run it is via `uvx` — no install step needed:

uvx mcp-sequential-thinking

Or install it permanently:

pip install mcp-sequential-thinking
mcp-sequential-thinking

Development Setup

To work on the code, clone the repository and set it up from source:

1. **Set Up Project**

   # Create and activate virtual environment
   uv venv
   .venv\Scripts\activate  # Windows
   source .venv/bin/activate  # Unix

   # Install package and dependencies
   uv pip install -e .

   # For development with testing tools
   uv pip install -e ".[dev]"

   # For all optional dependencies
   uv pip install -e ".[all]"

2. **Run the Server**

   # Run directly
   uv run -m mcp_sequential_thinking.server

   # Or use the installed script
   mcp-sequential-thinking

3. **Run Tests**

   # Run all tests
   pytest

   # Run with coverage report
   pytest --cov=mcp_sequential_thinking

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 188 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/arben-adm-mcp-sequential-thinking-badge.png)](https://mseep.ai/app/arben-adm-mcp-sequential-thinking)
  2. [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/0387db2d-476b-4b3d-852a-d55b4f67d888)
  3. # MCP Sequential Thinking
  4. [![MCP Toplist](https://mcptoplist.com/badge/glama%2Farben-adm%2Fmcp-sequential-thinking.svg)](https://mcptoplist.com/server/glama%2Farben-adm%2Fmcp-sequential-thinking)
  5. [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  7. [![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
  8. <!-- mcp-name: io.github.arben-adm/mcp-sequential-thinking -->
  9. A local MCP server for **working notes you can resume**: evidence, decisions, risks
  10. and next actions for a difficult task, stored durably in SQLite and readable after
  11. any restart. It records what the caller writes; it does not generate, judge or
  12. improve reasoning, and it never asks for hidden chain-of-thought.
  13. <a href="https://glama.ai/mcp/servers/m83dfy8feg"><img width="380" height="200" src="https://glama.ai/mcp/servers/m83dfy8feg/badge" alt="Sequential Thinking Server MCP server" /></a>
  14. ## Installation
  15. Published on [PyPI](https://pypi.org/project/mcp-sequential-thinking/) and in the
  16. [MCP Registry](https://registry.modelcontextprotocol.io/) as
  17. `io.github.arben-adm/mcp-sequential-thinking`. With [uv](https://docs.astral.sh/uv/)
  18. installed, `uvx mcp-sequential-thinking` runs it without a manual install
  19. (pin with `uvx mcp-sequential-thinking@0.7.0`). `MCP_STORAGE_DIR` is optional.
  20. **Claude Code**
  21. ```sh
  22. claude mcp add working-notes -- uvx mcp-sequential-thinking # this project only
  23. claude mcp add --scope user working-notes -- uvx mcp-sequential-thinking # all projects
  24. claude mcp add --scope project working-notes -- uvx mcp-sequential-thinking # shared via .mcp.json
  25. ```
  26. **Gemini CLI**
  27. ```sh
  28. gemini mcp add working-notes uvx mcp-sequential-thinking # writes .gemini/settings.json
  29. ```
  30. **Codex CLI**
  31. ```sh
  32. codex mcp add working-notes -- uvx mcp-sequential-thinking
  33. ```
  34. **Claude Desktop** (Settings → Developer → Edit Config, `claude_desktop_config.json`)
  35. ```json
  36. {"mcpServers":{"working-notes":{
  37. "command":"uvx",
  38. "args":["mcp-sequential-thinking"],
  39. "env":{"MCP_STORAGE_DIR":"/absolute/path/to/notes"}}}}
  40. ```
  41. Restart Claude Desktop afterwards.
  42. **VS Code** (`.vscode/mcp.json`)
  43. ```json
  44. {"servers":{"working-notes":{"type":"stdio","command":"uvx","args":["mcp-sequential-thinking"]}}}
  45. ```
  46. If a GUI client cannot find `uvx`, use its absolute path (`which uvx`).
  47. ### From source
  48. ```sh
  49. python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
  50. python -m pip install -e .
  51. python scripts/stdio_smoke.py # restart demo: write, restart, read back
  52. ```
  53. Then point the client at `/absolute/path/to/.venv/bin/mcp-sequential-thinking`
  54. (Windows: `.venv\Scripts\mcp-sequential-thinking.exe`) instead of `uvx`.
  55. ## Quick start
  56. A typical session:
  57. ```json
  58. {"tool":"create_session","arguments":{"title":"Choose a local store","request_id":"create-1"}}
  59. {"tool":"add_step","arguments":{"session_id":"<id>","content":"Two writers need unique positions.","kind":"evidence","request_id":"step-1"}}
  60. {"tool":"add_step","arguments":{"session_id":"<id>","content":"Use SQLite.","kind":"decision","request_id":"step-2"}}
  61. {"tool":"read_session","arguments":{"session_id":"<id>"}}
  62. ```
  63. Lost the ID after a restart? `list_sessions` finds the session by title.
  64. ## Tools
  65. | Tool | Purpose |
  66. | --- | --- |
  67. | `create_session` | Start a session from a title. |
  68. | `add_step` | Add a note; `kind` is `note` (default), `observation`, `evidence`, `assumption`, `option`, `risk`, `decision` or `next_action`. |
  69. | `list_sessions` | Find sessions by title or status. |
  70. | `read_session` | `view="resume"` (default): active notes, decisions first. `view="steps"`: full history with filters. |
  71. | `finalize_session` | Store the caller's outcome and evidence IDs; no further steps afterwards. |
  72. | `delete_session` | Delete a session's database records (exports and backups remain). |
  73. | `export_session` / `import_session` | JSON archive of one session, confined to `MCP_STORAGE_DIR/exports`. |
  74. **Links between notes.** `parent_step_id` records provenance, `supersedes_step_id`
  75. replaces an earlier note (resume hides it, full history keeps it), and
  76. `branch_from_step_id` starts a named branch. All references stay inside one session.
  77. **Retries.** Every write takes a `request_id`. Repeating a call with the same ID and
  78. input returns the original result; the same ID with different input returns
  79. `IDEMPOTENCY_CONFLICT`. `finalize_session` and `delete_session` also need
  80. `expected_version`.
  81. **Pagination and limits.** Reads default to 20 entries and 12,000 characters
  82. (`limit` ≤ 100, `max_chars` 1,000–50,000). Follow `cursor` until it is `null`, and
  83. keep the same `view` while paging. `truncated` reports shortened content. A note
  84. too large for one response comes back as its first chunk; continue with `step_id`
  85. and `content_offset` until `next_content_offset` is `null`.
  86. **Errors** set `isError=true` with a stable code and a short hint, e.g.
  87. `INVALID_INPUT` (with `Fields: …`), `UNKNOWN_SESSION`, `INVALID_REFERENCE`,
  88. `CONFLICT` (with `current_version`), `SESSION_FINALIZED`, `IDEMPOTENCY_CONFLICT`,
  89. `STORAGE_BUSY` (retry with the same `request_id`), `PATH_OUTSIDE_EXPORTS`,
  90. `RESPONSE_LIMIT`.
  91. Sources attached to notes are caller-supplied and never fetched or verified.
  92. ## Legacy tools (deprecated)
  93. `process_thought`, `generate_summary` and `clear_history`, plus `export_session` /
  94. `import_session` without a `session_id`, work on a single shared `legacy` session.
  95. They remain for existing clients; every result carries a `deprecation_notice`.
  96. Use the session API for new work.
  97. - Stages: Problem Definition, Research, Analysis, Synthesis, Conclusion
  98. (case-insensitive). Order warnings are advisory unless `--strict-stages` is set.
  99. - `main_line_progress` counts mainline notes only, against your `total_thoughts`;
  100. it is not task completion.
  101. - Legacy import **replaces** the legacy history.
  102. - `read_session(session_id="legacy")` reads it; a legacy branch `X` appears as
  103. `legacy-X` there.
  104. ## Storage and operation
  105. ```sh
  106. mcp-sequential-thinking # stdio server
  107. mcp-sequential-thinking --health # diagnostic check
  108. mcp-sequential-thinking --ephemeral # in memory only, lost on exit
  109. ```
  110. - Data lives in `~/.mcp_sequential_thinking` (or `MCP_STORAGE_DIR`) as **plaintext**
  111. SQLite (WAL, synchronous FULL, 5 s busy timeout). Use a local disk; NFS/SMB and
  112. multiple hosts are not supported.
  113. - Several stdio servers may share one store. Local stdio trusts the OS user; a
  114. session ID is not authorization. HTTP/SSE are experimental.
  115. - Deletion is not secure erasure. There is no automatic retention.
  116. - On first start, an existing 0.6 JSONL history migrates into SQLite in one
  117. transaction, keeping IDs and content; a backup of the source stays in place.
  118. Stop old 0.6 servers first. Downgrading after new writes is not supported.
  119. Backup and restore (all sessions, including retry keys):
  120. ```sh
  121. python -m mcp_sequential_thinking.backup create /path/to/storage /path/to/snapshot.sqlite3
  122. python -m mcp_sequential_thinking.backup restore /path/to/NEW-storage /path/to/snapshot.sqlite3
  123. ```
  124. Restore requires a new directory. Never copy a live database file without its WAL.
  125. ## Tested with
  126. | Client | OS | Date |
  127. | --- | --- | --- |
  128. | Python MCP SDK 2.0.0 and latest, Python 3.10–3.14 | Linux, Windows | every CI run |
  129. | Claude Desktop | Linux | 2026-10-21 |
  130. ## Development
  131. ```sh
  132. uv run --extra dev ruff check .
  133. uv run --extra dev ruff format --check .
  134. uv run --extra dev mypy --strict mcp_sequential_thinking
  135. uv run --extra dev pytest --cov=mcp_sequential_thinking --cov-fail-under=85
  136. rm -rf dist && uv run --extra dev --with build --with twine --with jsonschema python scripts/check_artifacts.py
  137. ```
  138. The artifact check builds and installs the wheel in isolation and runs a real
  139. restart round trip. Releases publish that tested artifact via Trusted Publishing
  140. once a GitHub release is created; the version lives in
  141. `mcp_sequential_thinking/_version.py`. See [CHANGELOG.md](CHANGELOG.md) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.