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]"

1. Run the Server

   # Run directly
   uv run -m mcp_sequential_thinking.server

   # Or use the installed script
   mcp-sequential-thinking

1. 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 (development)

If you have set up the project with uv venv && uv pip install -e ., point directly to the venv Python interpreter. This avoids dependency resolution issues (e.g., on systems with Python 3.14+):

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "/path/to/mcp-sequential-thinking/.venv/bin/python",
      "args": [
        "-m",
        "mcp_sequential_thinking.server"
      ],
      "cwd": "/path/to/mcp-sequential-thinking"
    }
  }
}

Option 4: Using uv run on a local clone (development)

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-sequential-thinking",
        "-m",
        "mcp_sequential_thinking.server"
      ]
    }
  }
}

Editor & IDE Integration

Cursor

Add to your Cursor MCP configuration at .cursor/mcp.json in your project root (or globally at ~/.cursor/mcp.json):

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

VS Code (Copilot MCP)

VS Code supports MCP servers since version 1.99+. Add to .vscode/mcp.json in your workspace or to your user settings.json:

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

Note: Enable MCP support in VS Code via "chat.mcp.enabled": true in your settings.

Zed

Add to your Zed settings (~/.config/zed/settings.json):

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

Claude Code (CLI)

Add the server using the CLI:

claude mcp add sequential-thinking -- uvx mcp-sequential-thinking

Or manually create/edit .mcp.json in your project root:

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

Windsurf

Add to your Windsurf MCP configuration at ~/.codeium/windsurf/mcp_config.json:

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

Gemini CLI

Add to your Gemini CLI settings at ~/.gemini/settings.json:

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