NiceGUI MCP

NiceGUI MCP is a docs-first Model Context Protocol server for local NiceGUI development. It bundles curated guidance, searches that guidance, analyzes pasted NiceGUI code for common problems, applies a narrow safe fixer set, and generates starter patterns for real app workflows.

What It Does

• Guidance lookup for common NiceGUI problem areas
• Topic search across bundled docs
• Static analysis for layout, scrolling, async, dialog, styling, and architecture issues
• Deterministic safe fixes for a small allowlisted set of patterns
• Starter generation for layout shells, dialogs, async flows, forms, tables, and controller/service splits

What It Does Not Do

• repo-wide indexing
• arbitrary code execution
• browser automation
• embeddings or vector search
• hosted multi-user deployment
• large-scale automated refactors

Bundled Topics

• layout_spacing_scrolling
• async_tasks_performance
• styling_theming
• dialogs
• state_management
• component_architecture
• forms_validation
• data_views_tables_charts
• testing
• deployment_runtime

Tools

• list_topics()
• get_guidance(topic)
• search_guidance(query, topics=None)
• analyze_nicegui_code(code, focus=None, filename=None, context=None)
• fix_nicegui_code(code, aggressive=False)
• generate_nicegui_component(kind, mode='default', details_json=None)

Resources

• nicegui://topics/index
• nicegui://guidance/{topic}

Recommended Workflow

1. Search or read guidance for the problem area.
2. Analyze the relevant NiceGUI snippet.
3. Apply safe fixes where the fixer set supports them.
4. Reanalyze the updated code.
5. Generate a better pattern when the issue is architectural rather than local.

Installation

uv sync

Run

uv run nicegui-mcp

Test

uv run pytest -q

Example MCP Client Config

{
  "mcpServers": {
    "nicegui-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/nicegui-mcp", "nicegui-mcp"]
    }
  }
}

Project Layout

nicegui_mcp/
├── analyzers.py
├── docs/
├── fixers.py
├── generators.py
├── models.py
├── profile.py
├── registry.py
└── server.py