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