---
title: Sequentialthinking Mcp
emoji: 🏢
colorFrom: purple
colorTo: gray
sdk: gradio
sdk_version: 6.11.0
app_file: app.py
pinned: false
short_description: Sequential Thinking MCP Server (Gradio + Python)
---

# Sequential Thinking — Gradio MCP Server

Python [Gradio](https://www.gradio.app/) app that exposes **Sequential Thinking** as an MCP server over SSE, alongside a small UI for manual thought steps. It mirrors the behaviour of the reference [Sequential Thinking MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) (TypeScript) using Gradio’s built-in MCP support (`gradio[mcp]`).

## What’s included

- **MCP over HTTP (SSE)** — connect any MCP client to the Gradio `/gradio_api/mcp/sse` endpoint  
- **Web UI** — process thoughts, reset session, inspect history, and copy-paste MCP config  
- **Structured thinking** — revisions, branches, adjustable totals, optional “needs more thoughts”  
- **Logging** — every thought is appended to `logs/chat_logs.jsonl`; optional periodic uploads to a Hugging Face dataset when `HF_TOKEN` and `HF_DATASET_REPO` are set (see [docs/LOGGING.md](docs/LOGGING.md))

## Requirements

- Python 3.10+ recommended  
- Dependencies: see [requirements.txt](requirements.txt) (`gradio[mcp]==6.11.0`)

## Run locally

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
python app.py
```

Gradio starts (default [http://localhost:7860](http://localhost:7860)). **MCP SSE URL:**

`http://localhost:7860/gradio_api/mcp/sse`

On Windows, if your default console encoding breaks Gradio’s startup output, use UTF-8, for example:

```bash
python -X utf8 app.py
```

**PowerShell helper:** [run.ps1](run.ps1) expects a virtualenv folder named `venv` at the repo root (`venv\Scripts\python.exe`). If you use `.venv` instead, activate it and run `python app.py` as above.

## MCP tools

| Tool                  | Description                                                      |
| --------------------- | ---------------------------------------------------------------- |
| `sequential_thinking` | Record one thinking step and return progress metadata            |
| `reset_session`       | Clear in-memory history and branches; new session id for logging |
| `get_history`         | Return the full thought list for the current session             |

### `sequential_thinking` parameters

Names follow the Python implementation (snake_case):

| Parameter             | Type    | Required | Description                              |
| --------------------- | ------- | -------- | ---------------------------------------- |
| `thought`             | string  | yes      | Current thinking step                    |
| `thought_number`      | integer | yes      | Step index (starts at 1)                 |
| `total_thoughts`      | integer | yes      | Estimated total steps (can grow)         |
| `next_thought_needed` | boolean | yes      | Whether another step is expected         |
| `is_revision`         | boolean | no       | This step revises earlier thinking       |
| `revises_thought`     | integer | no       | Which thought number is revised          |
| `branch_from_thought` | integer | no       | Branch from this thought number          |
| `branch_id`           | string  | no       | Label for the branch                     |
| `needs_more_thoughts` | boolean | no       | Extend beyond the current total estimate |

## Configure your MCP client

Point the client at the SSE URL (adjust host/port if you change Gradio’s `server_name` / `server_port`).

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "sequential-thinking": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}
```

### VS Code — user or workspace `mcp.json`

```json
{
  "servers": {
    "sequential-thinking": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}
```

See [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for file locations.

### Cursor

Add an MCP server entry with the same `url` as above (for example in your Cursor MCP configuration), with the app running locally.

## Environment variables

| Variable                  | Effect                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| `DISABLE_THOUGHT_LOGGING` | Set to `true` to suppress **console** banners for each thought (JSONL logging is unchanged) |
| `HF_TOKEN`                | Optional — Hugging Face token for dataset upload                                            |
| `HF_DATASET_REPO`         | Optional — dataset id (e.g. `username/my-logs`) used with `HF_TOKEN`                        |

Details: [docs/LOGGING.md](docs/LOGGING.md).

## Hugging Face Spaces

The YAML front matter at the top of this file is for Space deployment. After deploy, use your Space URL for MCP, for example:

`https://<your-space-name>.hf.space/gradio_api/mcp/sse`

## Relation to other packages

The npm package `@modelcontextprotocol/server-sequential-thinking` and the `mcp/sequentialthinking` Docker image are **separate** official distributions. **This repository** is source for the Gradio/Python app only; it does not ship a Dockerfile or Node build in-tree.

## Docs

- [docs/LOGGING.md](docs/LOGGING.md) — log format, Hugging Face upload, troubleshooting  
- [docs/IMPLEMENTATION_SUMMARY.md](docs/IMPLEMENTATION_SUMMARY.md) — logging implementation notes