MCP Brainstorm Server

An MCP (Model Context Protocol) server that spawns a lightweight, resource-efficient localhost UI for interactive AI-assisted brainstorming, planning, and visualization. Designed to work seamlessly with Claude and other AI agents for collaborative ideation workflows.

What It Does

Core Workflow

1. Detection: When you mention brainstorming keywords (brainstorm, plan, think, how do...), the AI agent asks if you want to use the interactive UI

2. Launch: Server starts on localhost with a session-specific URL

3. Interaction: Render brainstorming materials using mermaid diagrams or Tailwind-styled HTML UI

4. Submission: Users interact with clickable buttons, input comments, and optionally upload/paste images

5. Retrieval: AI agent reads submitted responses to continue work

6. Documentation: Optional saving to plans/*.md for future reference

Features

• Multi-Session Support: Each AI agent session gets its own URL (localhost:{port}/{sessionid}) with tab names reflecting working directory for easy distinction

• Shared Single Install Across Agents: One local clone and one Python environment can be reused by Claude, Codex, and other MCP-compatible agents at the same time, so you install once per machine instead of once per agent

• Rich Content Rendering:

  • Mermaid diagrams for graphs, flowcharts, and visualizations

  • Tailwind CSS-styled UI for brainstorming options and interfaces

  • Markdown-compatible format renderer with embedded diagrams and tables

• Interactive Elements:

  • Auto-generated IDs for sections and options (for easy reference)

  • Clickable buttons for user choices

  • Inline comment input fields

  • Submit/Done workflow

• Image Support:

  • Local file upload via file picker

  • Internet-accessible URLs

  • Clipboard paste-in capability

• Resource Efficient: Lightweight Python server designed for single-user operation

• Loopback Only: The HTTP UI is hard-limited to loopback addresses and rejects non-local clients

Architecture

Components

├── mcp_server.py          # MCP server implementation (Python)
├── server/                # localhost UI server
│   ├── app.py            # Flask/FastAPI server
│   ├── templates/        # HTML templates
│   └── static/           # CSS, JS, assets
└── requirements.txt      # Dependencies

Runtime data is stored outside the repository by default under ~/.mcp/brainstorm-mcp/:

~/.mcp/brainstorm-mcp/
├── sessions/             # Session state storage
│   └── assets/           # Uploaded or pasted image data
├── plans/                # User-saved markdown plans
└── preferences/          # Brainstorm preferences (instructions to the AI)
    ├── global.json       # Machine-wide defaults
    └── projects/         # Per-project overrides, keyed by hashed absolute path

Per-project preferences live under the central data root (never inside the project repo), so configuring a project never adds files to that project's working tree.

Session Management

• Each session gets a unique sessionid (UUID or similar)

• Session state stored in lightweight persistent storage under the user's ~/.mcp/brainstorm-mcp/ directory by default

• URLs: localhost:PORT/{sessionid}

• Tab titles reflect the working directory (pwd) of the AI agent terminal

Tech Stack

• MCP Framework: Python MCP SDK

• Backend: Python (Flask/FastAPI for lightweight HTTP server)

• Frontend Rendering:

  • Diagrams: Mermaid.js

  • UI/Styling: Tailwind CSS

  • Markdown: Compatible format with embedded Mermaid support

• Storage: JSON/SQLite (minimal, for session state)

Installation & Usage

Prerequisites

• Python 3.9+

• MCP client (Claude or compatible AI agent)

Full Installation Guide

For complete installation instructions, including:

• using an existing local clone

• cloning into the recommended shared MCP server location

• connecting the server to Codex

• connecting the server to Claude Code

• reusing one install across multiple agents

See INSTALL.md.

Setup

git clone <repo-url>
cd mcp-brainstorm-server
pip install -r requirements.txt

Running the Server

The server is started on-demand by the MCP tool when the AI agent detects brainstorming keywords. Users can also manually start it:

python mcp_server.py

Expected Dependencies

anthropic-mcp
flask  # or fastapi
pydantic
python-dotenv

Protocol Flow

Example: Planning a Feature

1. User: "Let me brainstorm the architecture for this feature"

2. AI Agent: Detects keyword → Asks "Should I open the interactive brainstorming UI?"

3. User: "Yes"

4. Server: Launches at localhost:8080/abc-def-123-ghi (sessionid based on pwd)

5. UI: Renders mermaid diagram of possible architectures with clickable options, comment fields, and image upload area

6. User: Clicks preferred architecture option, adds comments, optionally uploads a reference diagram

7. User: Clicks "Submit"

8. Server: Stores submission under sessionid

9. User: Returns to AI agent and says "response submitted"

10. AI Agent: Retrieves submission via MCP → Continues planning with the user's input

11. AI Agent (optional): "Should I save this plan? Suggested location: plans/feature-architecture.md" Default saved location on disk: ~/.mcp/brainstorm-mcp/plans/feature-architecture.md

MCP Tool Specification

Available Tools

start_brainstorm_session

Starts an interactive brainstorming UI session.

Input:

• prompt (str): Initial brainstorming prompt/context

• content_type (str): "mermaid", "html", or "markdown"

• working_dir (str, optional): Current working directory (used for tab title)

Output:

• session_id (str): Unique session identifier

• url (str): Full localhost URL to access the UI

• port (int): Port number used

get_session_response

Retrieves user submission from a completed session.

Input:

• session_id (str): Session identifier

Output:

• response (dict): User's submitted choices, comments, and images

• timestamp (str): When submission occurred

• status (str): "pending", "submitted", "expired"

list_sessions

Lists all active sessions.

Output:

• sessions (list): Array of active session objects with IDs, URLs, and creation times

close_session

Terminates and cleans up a session.

Input:

• session_id (str): Session to close

set_brainstorm_preferences

Saves user-facing instructions that shape how the AI brainstorms. Any field left unset preserves the prior value, so you can update one field at a time.

Input:

• scope (str): "global" (machine-wide default) or "project" (override for one project — requires project_path)

• project_path (str, optional): Absolute path to the project. Required when scope="project". Used as the lookup key; the file itself is stored centrally under ~/.mcp/brainstorm-mcp/preferences/projects/.

• uiux_level (str, optional): User's UI/UX skill level (free text). Suggested values: never_before, amateur, intermediate, expert.

• uiux_style (str, optional): Project's UI/UX style (free text). Examples: corporate internal tool, marketing-heavy landing page, children education app.

• questioning_style (str, optional): How the AI should question the user. Suggested values: autonomous_review (AI builds, user reviews with as few questions as possible) or collaborative_stepwise (AI brainstorms step by step, asking many questions to converge on the imagined UI).

Output: Effective preferences after the merge (project overrides global, field by field), plus the source of each field.

get_brainstorm_preferences

Reads the effective brainstorm preferences. Project values override global values field by field.

Input:

• project_path (str, optional): Absolute project path to merge into the global defaults. Omit to read globals only.

Output: Same shape as set_brainstorm_preferences. The AI also receives this object inline on every start_brainstorm_session response, so it never needs to ask twice.

Design Principles

• Minimal Resource Usage: Single-user operation, no heavy dependencies

• Stateless Where Possible: Sessions are ephemeral unless saved to disk

• Ease of Reference: Auto-generated IDs on all interactive elements

• AI-Agent Friendly: Structured response format for easy parsing and continuation

• Visual Clarity: Clear separation of UI sections with markdown/mermaid rendering

Future Enhancements

• Persistent session history

• Real-time collaboration (future multi-user support)

• Custom Tailwind component library for brainstorming templates

• Built-in export to various formats (PDF, PNG, etc.)

• Integration with git for automatic plan versioning

License

MIT

Contributing

Contributions welcome. Please follow PEP 8 for Python code and ensure the server remains lightweight.