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.
Badge for your README
Markdown
[](/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
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.
- [](https://mseep.ai/app/arben-adm-mcp-sequential-thinking)
- [](https://mseep.ai/app/0387db2d-476b-4b3d-852a-d55b4f67d888)
- # MCP Sequential Thinking
- [](https://mcptoplist.com/server/glama%2Farben-adm%2Fmcp-sequential-thinking)
- [](https://www.python.org/downloads/)
- [](https://opensource.org/licenses/MIT)
- [](https://github.com/astral-sh/ruff)
- <!-- mcp-name: io.github.arben-adm/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.
- <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>
- ## Installation
- Published on [PyPI](https://pypi.org/project/mcp-sequential-thinking/) and in the
- [MCP Registry](https://registry.modelcontextprotocol.io/) as
- `io.github.arben-adm/mcp-sequential-thinking`. With [uv](https://docs.astral.sh/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**
- ```sh
- 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**
- ```sh
- gemini mcp add working-notes uvx mcp-sequential-thinking # writes .gemini/settings.json
- ```
- **Codex CLI**
- ```sh
- codex mcp add working-notes -- uvx mcp-sequential-thinking
- ```
- **Claude Desktop** (Settings → Developer → Edit Config, `claude_desktop_config.json`)
- ```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`)
- ```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
- ```sh
- 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`.
- ## Quick start
- A typical session:
- ```json
- {"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
- ```sh
- 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):
- ```sh
- 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
- ```sh
- 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](CHANGELOG.md) for details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.