Sequential Thinking MCP Server

A Model Context Protocol (MCP) server that facilitates structured, progressive thinking through defined stages. This tool helps break down complex problems into sequential thoughts, track the progression of your thinking process, and generate summaries.

<a href="https://glama.ai/mcp/servers/m83dfy8feg"></a>

Features

- Structured Thinking Framework: Organizes thoughts through standard cognitive stages (Problem Definition, Research, Analysis, Synthesis, Conclusion)
- 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
- Related Thought Analysis: Identifies connections between similar thoughts
- Progress Monitoring: Tracks your position in the overall thinking sequence
- Summary Generation: Creates concise overviews of the entire thought process
- 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: Graceful handling of edge cases and corrupted data
- Type Safety: Comprehensive type annotations and validation

Prerequisites

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

Key Technologies

- Pydantic: For data validation and serialization
- Portalocker: For thread-safe file access
- FastMCP: 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 (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": {}
    }
  }
}

> Tip: All editor configurations above run the published PyPI package via uvx. To run from a local clone instead (e.g. for development), use uv run --directory /path/to/mcp-sequential-thinking -m mcp_sequential_thinking.server or point directly to the venv Python interpreter (see Claude Desktop Options 3 and 4).