Sequential Thinking MCP Server

A Model Context Protocol (MCP) server providing a structured thinking journal: schema-validated thoughts, an append-only audit trail, structural analysis, and session export/import. It records and organizes a thinking process through defined stages — it does not evaluate, generate, or improve the reasoning itself; that stays with whatever model is calling it.

Features

• Structured Thinking Framework: Organizes thoughts through standard cognitive stages (Problem Definition, Research, Analysis, Synthesis, Conclusion), with warnings (or, in --strict-stages mode, rejection) when a thought skips or backtracks a stage
• Revisions & Branching: Revise earlier thoughts or fork alternative lines of reasoning, with revision- and branch-aware analysis and summaries
• Thought Tracking: Records and manages sequential thoughts with metadata as a structured, typed audit trail (structured_content on every tool response)
• Related Thought Analysis: Finds thoughts that are lexically similar to the current one, independent of stage, plus a separate same-tag/same-stage grouping — a categorical signal, not a claim of semantic relevance
• Progress Monitoring: Explicit mainline position, total recorded thoughts, branch count, and revision count — not a single ambiguous percentage
• Summary Generation: Extracts the actual recorded thinking (per-stage excerpts, aggregated challenged assumptions, open branches, revision chains) alongside structural statistics — a deterministic extraction, not new reasoning
• Persistent Storage: Append-only JSONL session log with thread-safety and automatic crash recovery
• Data Import/Export: Share and reuse thinking sessions
• Extensible Architecture: Easily customize and extend functionality
• Robust Error Handling: Protocol/validation errors (bad stage, duplicate thought number, path traversal) fail the call outright; execution errors the caller can adapt to come back as a normal tool result
• Type Safety: Comprehensive type annotations (mypy --strict clean) and Pydantic validation, including declared output schemas for every tool

Prerequisites

• Python 3.10 or higher
• UV package manager (Install Guide)

Key Technologies

• Pydantic: For data validation, serialization, and structured tool output schemas
• Portalocker: For thread-safe file access
• MCP Python SDK 2.x (mcp.server.mcpserver.MCPServer): For Model Context Protocol integration

Project Structure

mcp-sequential-thinking/
├── mcp_sequential_thinking/
│   ├── server.py       # Main server implementation and MCP tools
│   ├── models.py       # Data models with Pydantic validation
│   ├── storage.py      # Thread-safe persistence layer
│   ├── storage_utils.py # Shared utilities for storage operations
│   ├── analysis.py     # Thought analysis and pattern detection
│   ├── utils.py        # Common utilities and helper functions
│   ├── logging_conf.py # Centralized logging configuration
│   └── __init__.py     # Package initialization
├── tests/              
│   ├── test_analysis.py # Tests for analysis functionality
│   ├── test_models.py   # Tests for data models
│   ├── test_storage.py  # Tests for persistence layer
│   └── __init__.py
├── run_server.py       # Server entry point script
├── debug_mcp_connection.py # Utility for debugging connections
├── README.md           # Main documentation
├── CHANGELOG.md        # Version history and changes
├── example.md          # Customization examples
├── LICENSE             # MIT License
└── pyproject.toml      # Project configuration and dependencies

Quick Start

The package is published on PyPI as 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
   

Claude Desktop Integration

Add to your Claude Desktop configuration:

• Linux: ~/.config/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Using uvx with the PyPI package (recommended)

No clone, no venv, no manual updates — uvx fetches the package from PyPI and runs it:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "uvx",
      "args": ["mcp-sequential-thinking"]
    }
  }
}

To test unreleased changes, point uvx at the repository instead:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/arben-adm/mcp-sequential-thinking",
        "mcp-sequential-thinking"
      ]
    }
  }
}

Option 2: Using the installed entry point

If you've installed the package with pip install mcp-sequential-thinking (or pip install -e . from a clone):

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "mcp-sequential-thinking"
    }
  }
}

Option 3: Using a local clone's virtual environment (dev