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.