Sequential Thinking MCP Server (Python)

A Python implementation of the MCP server for dynamic and reflective problem-solving through a structured thinking process.

This is a Python port of the TypeScript @modelcontextprotocol/server-sequential-thinking package, providing the same functionality and API.

Features

• Break down complex problems into manageable steps
• Revise and refine thoughts as understanding deepens
• Branch into alternative paths of reasoning
• Adjust the total number of thoughts dynamically
• Generate and verify solution hypotheses
• Full compatibility with the TypeScript version

Installation

Using pip

pip install mcp-server-sequential-thinking

Using uv

uv add mcp-server-sequential-thinking

Using uvx (for running directly)

uvx mcp-server-sequential-thinking

Configuration

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

uvx (Recommended)

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

Python

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "python",
      "args": [
        "-m",
        "sequential_thinking"
      ]
    }
  }
}

Docker

{
  "mcpServers": {
    "sequentialthinking": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "mcp/sequentialthinking-python"
      ]
    }
  }
}

To disable logging of thought information set env var: DISABLE_THOUGHT_LOGGING to true.

Usage with VS Code

uvx installation:

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

Python installation:

{
  "servers": {
    "sequential-thinking": {
      "command": "python",
      "args": [
        "-m",
        "sequential_thinking"
      ]
    }
  }
}

For Docker installation:

{
  "servers": {
    "sequential-thinking": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "mcp/sequentialthinking-python"
      ]
    }
  }
}

Usage with Codex CLI

Run the following:

uvx

codex mcp add sequential-thinking uvx mcp-server-sequential-thinking

Python

codex mcp add sequential-thinking python -m sequential_thinking

Tools

sequentialthinking

Facilitates a detailed, step-by-step thinking process for problem-solving and analysis.

Input Parameters:

• thought (string, required): The current thinking step
• nextThoughtNeeded (boolean, required): Whether another thought step is needed
• thoughtNumber (integer, required): Current thought number (starting from 1)
• totalThoughts (integer, required): Estimated total thoughts needed
• isRevision (boolean, optional): Whether this revises previous thinking
• revisesThought (integer, optional): Which thought is being reconsidered
• branchFromThought (integer, optional): Branching point thought number
• branchId (string, optional): Branch identifier
• needsMoreThoughts (boolean, optional): If more thoughts are needed

Output:

{
  "thoughtNumber": 3,
  "totalThoughts": 5,
  "nextThoughtNeeded": true,
  "branches": ["branch-a", "branch-b"],
  "thoughtHistoryLength": 7
}

Usage Examples

Basic Problem Solving

# Step 1: Understand the problem
{
  "thought": "Let me understand this problem...",
  "thoughtNumber": 1,
  "totalThoughts": 4,
  "nextThoughtNeeded": true
}

# Step 2: Analyze
{
  "thought": "Analyzing the components...",
  "thoughtNumber": 2,
  "totalThoughts": 4,
  "nextThoughtNeeded": true
}

# Step 3: Solution
{
  "thought": "The solution is...",
  "thoughtNumber": 3,
  "totalThoughts": 4,
  "nextThoughtNeeded": false
}

With Revision

{
  "thought": "I need to revise my previous analysis...",
  "thoughtNumber": 2,
  "totalThoughts": 4,
  "nextThoughtNeeded": true,
  "isRevision": true,
  "revisesThought": 1
}

Branching

{
  "thought": "Exploring alternative approach A...",
  "thoughtNumber": 2,
  "totalThoughts": 3,
  "nextThoughtNeeded": false,
  "branchFromThought": 1,
  "branchId": "approach-a"
}

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/sequential-thinking-python

# Create virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
uv pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=sequential_thinking --cov-report=html

# Run specific test
pytest tests/test_lib.py::TestSequentialThinkingServer::test_accept_valid_basic_thought

Code Formatting and Linting

# Format code
black sequential_thinking/ tests/

# Sort imports
isort sequential_thinking/ tests/

# Type checking
mypy sequential_thinking/

Building

# Build wheel
python -m build

# Build with uv
uv build

Running Directly

# Using Python
python -m sequential_thinking

# Using uvx
uvx mcp-server-sequential-thinking

Docker

Build Docker Image

docker build -t mcp/sequentialthinking-python -f Dockerfile .

Run Docker Container

docker run --rm -i mcp/sequentialthinking-python

Environment Variables

• DISABLE_THOUGHT_LOGGING: Set to true to disable console output of thoughts (default: false)

Comparison with TypeScript Version

This Python implementation is designed to be a drop-in replacement for the TypeScript version with the following differences:

• Language: Python instead of TypeScript
• Runtime: Uses Python MCP SDK instead of TypeScript SDK
• Installation: Available via pip/uvx instead of npm/npx
• Performance: Similar performance characteristics
• API: Identical tool interface and behavior
• Features: All features from the TypeScript version are supported

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Support

For support, please:

• Check the MCP documentation
• Open an issue in the GitHub repository
• Join the discussions in the community forum