Flutter MCP: Give Your AI Real-Time Flutter Superpowers 🚀

A real-time MCP server providing Flutter/Dart documentation and pub.dev package info to AI assistants — supports ALL 50,000+ packages on demand.

Stop fighting with hallucinated widgets and deprecated APIs. Flutter MCP connects your AI assistant to real-time documentation, ensuring the Flutter code it generates actually works.

Quick Start • Demo • Features • How it Works • Contributing

🎬 Demo

See it in action: From npx flutter-mcp to getting real-time Flutter documentation in 20 seconds.

The Problem: Your AI is Stuck in 2021

😡 Without Flutter MCP

// User: "How do I use Riverpod to watch a future?"

// AI generates (outdated):
final userProvider = FutureProvider((ref) async {
  return fetchUser();
});

// WRONG! Missing autoDispose, family, etc.

Result: Deprecation warnings, confused debugging, time wasted on Google

✅ With Flutter MCP

// User: "How do I use @flutter_mcp riverpod:^2.5.0 to watch a future?"

// AI generates (using v2.5.1 docs):
final userProvider = FutureProvider.autoDispose
  .family<User, String>((ref, userId) async {
    return ref.watch(apiProvider).fetchUser(userId);
});

// Correct, version-specific, actually works!

Result: Code works immediately, you ship faster

🚀 Quick Start

Installation

Get started in seconds with npm:

# One-line usage (no installation required)
npx flutter-mcp

# Or install globally
npm install -g flutter-mcp
flutter-mcp

That's it! No Python setup, no configuration, no complexity. The server automatically installs dependencies and starts running.

📢 For MCP SuperAssistant Users: Use npx flutter-mcp --transport http --port 8000 to enable HTTP transport!

Alternative Installation Methods

🐍 Python Package (pip)

If you prefer using Python directly:

# Install from GitHub (PyPI package coming soon)
pip install git+https://github.com/adamsmaka/flutter-mcp.git

# Run the server
flutter-mcp-server start

🔧 Install from Source

For development or customization:

# Clone the repository
git clone https://github.com/adamsmaka/flutter-mcp.git
cd flutter-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Run the server
flutter-mcp-server start

🐳 Docker

For containerized deployments:

# Docker image coming soon
# Run with Docker (once published)
# docker run -d -p 8000:8000 ghcr.io/adamsmaka/flutter-mcp:latest

# For now, use local development setup instead
pip install git+https://github.com/adamsmaka/flutter-mcp.git

🎯 Single Executable (Coming Soon)

# Download for your platform
curl -L https://github.com/flutter-mcp/flutter-mcp/releases/latest/flutter-mcp-macos -o flutter-mcp
chmod +x flutter-mcp
./flutter-mcp

No Python, no pip, just download and run!

Requirements

Node.js 16+ (for npm/npx)
Python 3.10+ is auto-detected and used by the npm package
That's it! Built-in SQLite caching means no external dependencies

2. Add to Your AI Assistant

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "flutter-docs": {
      "command": "npx",
      "args": ["flutter-mcp"]
    }
  }
}

Or if you installed globally:

{
  "mcpServers": {
    "flutter-docs": {
      "command": "flutter-mcp"
    }
  }
}

Restart Claude Desktop after saving. The server will automatically install dependencies on first run.

Claude Code (claude.ai/code)

Create a .mcp.json file in your Flutter project root:

{
  "mcpServers": {
    "flutter-docs": {
      "command": "npx",
      "args": ["flutter-mcp"]
    }
  }
}

Then run Claude Code in your project directory:

cd your-flutter-project
claude

Flutter MCP will automatically provide documentation for all packages in your pubspec.yaml.

Alternative: Global npm install

If you installed globally with npm install -g flutter-mcp:

{
  "mcpServers": {
    "flutter-docs": {
      "command": "flutter-mcp"
    }
  }
}

Important: Don't use the --dangerously-skip-permissions flag when running Claude Code, as it prevents MCP servers from being loaded.

Cursor / Windsurf

In Settings → MCP Servers, add:

{
  "flutter-docs": {
    "command": "npx",
    "args": ["flutter-mcp"]
  }
}

MCP SuperAssistant

MCP SuperAssistant requires HTTP transport. Configure it with:

Start the server with HTTP transport:

npx flutter-mcp --transport http --port 8000

In MCP SuperAssistant, add a new server:
- Name: Flutter MCP
- URL: http://localhost:8000
- Type: HTTP MCP Server
The server will now be available in your MCP SuperAssistant client.

VS Code + Continue

In your .continuerc.json:

{
  "models": [
    {
      "provider": "claude",
      "mcp_servers": {
        "flutter-docs": {
          "command": "npx",
          "args": ["flutter-mcp"]
        }
      }
    }
  ]
}

3. Start the Server (Optional for Testing)

Manual server control and transport options

# Default STDIO mode (for Claude Desktop)
npx flutter-mcp

# HTTP transport (for MCP SuperAssistant)
npx flutter-mcp --transport http --port 8000

# SSE transport
npx flutter-mcp --transport sse --port 8080

# Custom host binding
npx flutter-mcp --transport http --host 0.0.0.0 --port 3000

# If installed globally
flutter-mcp-server --transport http --port 8000

Transport Options:

Default (no flag) - STDIO for Claude Desktop and most MCP clients
--transport http - For HTTP-based clients like MCP SuperAssistant
--transport sse - For Server-Sent Events based clients
--port PORT - Port for HTTP/SSE transport (default: 8000)
--host HOST - Host to bind to (default: 127.0.0.1)

Note: When configured in Claude Desktop, the server starts automatically using STDIO transport.

3. Use It!

Flutter MCP now features simplified tools following Context7's successful pattern - just 2 main tools instead of 5!

🎯 New Simplified Usage (Recommended)

The AI assistant can now use Flutter MCP more intelligently:

# Universal search
"Search for Flutter animation widgets"
"Find state management packages" 
"Look for HTTP clients in pub.dev"

# Smart documentation fetching
"Show me Container widget documentation"
"Get the docs for provider package"
"Explain dart:async Future class"

💫 Natural Language Support

Your AI will automatically detect Flutter/Dart content and fetch relevant docs:

"How do I implement infinite scroll with infinite_scroll_pagination?"
"Show me dio interceptors for auth tokens"
"What's the difference between bloc and riverpod?"

🔧 Legacy Support

The @flutter_mcp mentions still work for backward compatibility:

"Explain @flutter_mcp freezed code generation"
"Show me all @flutter_mcp get_it service locator patterns"

🎯 Version-Specific Documentation (NEW!)

Get documentation for specific package versions using familiar pub.dev syntax:

# Exact versions
"Show me @flutter_mcp provider:6.0.5 breaking changes"
"How does @flutter_mcp riverpod:2.5.1 AsyncNotifier work?"

# Version ranges
"Compare @flutter_mcp dio:^5.0.0 vs @flutter_mcp dio:^4.0.0"
"What's new in @flutter_mcp bloc:>=8.0.0?"

# Special keywords
"Try @flutter_mcp get:latest experimental features"
"Is @flutter_mcp provider:stable production ready?"

See Version Specification Guide for details.

📚 Available Tools

🎯 NEW: Simplified Tools (Context7-style)

Flutter MCP now provides just 2 main tools, making it easier for AI assistants to use:

1. `flutter_search` - Universal Search

Search across Flutter/Dart documentation and pub.dev packages with intelligent ranking.

{
  "tool": "flutter_search",
  "arguments": {
    "query": "state management",
    "limit": 10  // Optional: max results (default: 10)
  }
}

Returns multiple options for the AI to choose from, including Flutter classes, Dart libraries, pub packages, and concepts.

2. `flutter_docs` - Smart Documentation Fetcher

Get documentation for any Flutter/Dart identifier with automatic type detection.

{
  "tool": "flutter_docs",
  "arguments": {
    "identifier": "Container",              // Auto-detects as Flutter widget
    "topic": "examples",                    // Optional: filter content
    "max_tokens": 10000                     // Optional: limit response size
  }
}

Supports various formats:

"Container" - Flutter widget
"material.AppBar" - Library-qualified class
"provider" - pub.dev package
"dart:async.Future" - Dart core library

3. `flutter_status` - Health Check (Optional)

Monitor service health and cache statistics.

{
  "tool": "flutter_status",
  "arguments": {}
}

📦 Legacy Tools (Deprecated but still functional)

The following tools are maintained for backward compatibility but internally use the new simplified tools:

View legacy tools

`get_flutter_docs` (Use `flutter_docs` instead)

{
  "tool": "get_flutter_docs",
  "arguments": {
    "class_name": "Container",
    "library": "widgets"
  }
}

`get_pub_package_info` (Use `flutter_docs` instead)

{
  "tool": "get_pub_package_info",
  "arguments": {
    "package_name": "provider",
    "version": "6.0.5"
  }
}

`search_flutter_docs` (Use `flutter_search` instead)

{
  "tool": "search_flutter_docs",
  "arguments": {
    "query": "material.AppBar"
  }
}

`process_flutter_mentions` (Still functional)

{
  "tool": "process_flutter_mentions",
  "arguments": {
    "text": "I need help with @flutter_mcp riverpod state management"
  }
}

`health_check` (Use `flutter_status` instead)

{
  "tool": "health_check",
  "arguments": {}
}

🎯 Features

✨ NEW: Simplified Tools: Just 2 main tools instead of 5 - following Context7's successful pattern
📦 Real-Time Documentation: Fetches the latest docs for any pub.dev package on-demand
🎯 Version-Specific Docs: Request exact versions, ranges, or use keywords like latest/stable
🚀 Zero Configuration: Automatically detects packages from your pubspec.yaml
⚡ Lightning Fast: Intelligent caching means instant responses after first fetch
🔒 100% Private: Runs locally - your code never leaves your machine
🎨 Smart Context: Provides constructors, methods, examples, and migration guides
♾️ Unlimited Packages: Works with all 50,000+ packages on pub.dev
🤖 AI-Optimized: Token limiting and smart truncation for efficient LLM usage

💡 How It Works

Flutter MCP is a local MCP server (think of it as a "RAG sidecar" for Flutter) built on the battle-tested Python MCP SDK. It enhances your AI with real-time documentation:

graph LR
    A[Your Prompt] --> B[AI Assistant]
    B --> C{Flutter/Dart Content?}
    C -->|Yes| D[Query Flutter MCP]
    D --> E[Check Local Cache]
    E -->|Hit| F[Return Cached Docs]
    E -->|Miss| G[Fetch from pub.dev]
    G --> H[Process & Cache]
    H --> F
    F --> I[Enhanced Context]
    I --> J[AI Generates Accurate Code]
    C -->|No| J

The Magic Behind the Scenes

MCP Integration: Your AI assistant automatically detects when you're asking about Flutter/Dart packages
Smart Detection: No special syntax required - just mention package names naturally
Lightning Cache: First request fetches from pub.dev (1-2 seconds), subsequent requests are instant
Context Injection: Documentation is seamlessly added to your AI's knowledge before it responds
Privacy First: Everything runs locally - your code and queries never leave your machine

Performance Notes

⚡ First Query: 1-2 seconds (fetching from pub.dev)
🚀 Cached Queries: <50ms (from local SQLite cache)
💾 Cache Duration: 24 hours for API docs, 12 hours for packages
🧹 Auto-Cleanup: Expired entries cleaned on access

Error Handling

If documentation isn't available or a fetch fails, Flutter MCP gracefully informs your AI, preventing it from generating incorrect or hallucinated code based on missing information. Your AI will let you know it couldn't find the docs rather than guessing.

📊 What Gets Indexed

When you request a package, Flutter MCP extracts:

✅ API Documentation: Classes, methods, properties with full signatures
✅ Constructors: All parameters, named arguments, defaults
✅ Code Examples: From official docs and README files
✅ Migration Guides: Breaking changes and upgrade paths
✅ Package Metadata: Dependencies, platform support, versions

🛠️ Advanced Usage

Debug Commands

# Run with debug logging
DEBUG=true npx flutter-mcp

# Check server status and cache info
flutter-mcp-server --help

Note: Cache is automatically managed by the server. Cached documentation expires after 24 hours (API docs) or 12 hours (packages).

Docker Deployment

For production or team use:

# Run the server (Docker image coming soon)
# docker run -d -p 8000:8000 --name flutter-mcp ghcr.io/adamsmaka/flutter-mcp:latest

# Check logs
docker logs -f flutter-mcp

🛠️ Troubleshooting

Error: spawn flutter-mcp ENOENT

This error means the system cannot find the flutter-mcp command. Solutions:

Use npx (recommended):

{
  "mcpServers": {
    "flutter-docs": {
      "command": "npx",
      "args": ["flutter-mcp"]
    }
  }
}

Install globally first:

npm install -g flutter-mcp
# Then use:
{
  "mcpServers": {
    "flutter-docs": {
      "command": "flutter-mcp"
    }
  }
}

Check Node.js installation:

node --version  # Should be 16+
npm --version   # Should be installed

MCP server failed to start

Check if Node.js 16+ is installed: node --version
Try running manually to see errors: npx flutter-mcp
The npm package will auto-install Python dependencies on first run
Check if Python 3.8+ is available: python3 --version
View detailed logs: DEBUG=true npx flutter-mcp

Documentation not found errors

Some very new packages might not have documentation yet
Private packages are not supported
Try using the package name exactly as it appears on pub.dev

Cannot connect from MCP client

Different MCP clients require different transport protocols:

Claude Desktop: Uses STDIO transport (default)
- No port/URL needed
- Just use: npx flutter-mcp
MCP SuperAssistant: Requires HTTP transport
- Start with: npx flutter-mcp --transport http --port 8000
- Connect to: http://localhost:8000
Custom clients: May need SSE transport
- Start with: npx flutter-mcp --transport sse --port 8080
- SSE endpoint: http://localhost:8080/sse

If connection fails:

Verify the correct transport mode for your client
Check if the port is already in use
Try binding to all interfaces: --host 0.0.0.0
Ensure Node.js and npm are properly installed

📱 Client Configurations

Need help configuring your MCP client? We have detailed guides for:

Claude Desktop
MCP SuperAssistant
Claude Code
VS Code + Continue
Custom HTTP/SSE clients
Docker configurations

→ View all client configuration examples

🤝 Contributing

We love contributions! This is an open-source project and we welcome improvements.

→ Read our Contributing Guide

Quick Ways to Contribute

🐛 Report bugs - Open an issue
💡 Suggest features - Start a discussion
📖 Improve docs - Even fixing a typo helps!
🧪 Add tests - Help us reach 100% coverage
🌐 Add translations - Make Flutter MCP accessible globally
⭐ Star the repo - Help others discover Flutter MCP

🚀 What's New & Coming Soon

Recently Released:

✅ Simplified Tools: Reduced from 5 tools to just 2 main tools (Context7-style)
✅ Smart Detection: Auto-detects Flutter widgets, Dart classes, and pub packages
✅ Token Limiting: Default 10,000 tokens with smart truncation
✅ Topic Filtering: Focus on specific sections (examples, constructors, etc.)

On our roadmap:

📚 Stack Overflow integration for common Flutter questions
🎯 Natural language activation: "use flutter docs" pattern
🌍 Offline mode for airplane coding
🚀 Hosted service option for teams

Want to help build these features? Join us!

❤️ Spread the Word

Help other Flutter developers discover AI superpowers:

Add the badge to your project:

[![Flutter MCP](https://img.shields.io/badge/Enhanced%20by-Flutter%20MCP-blue)](https://github.com/flutter-mcp/flutter-mcp)

📄 License

🏗️ Built With

Python MCP SDK - The most popular MCP implementation (14k+ stars)
FastMCP - High-level Python framework for MCP servers
SQLite - Built-in caching with zero configuration
npm/npx - Simple one-line installation and execution
BeautifulSoup - Robust HTML parsing
httpx - Modern async HTTP client

Ready to give your AI Flutter superpowers?

Get Started • Report Bug • Request Feature

Made with ❤️ by the Flutter community

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.github/workflows		.github/workflows
docker		docker
docs		docs
examples		examples
npm-wrapper		npm-wrapper
scripts		scripts
src/flutter_mcp		src/flutter_mcp
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.pypirc.template		.pypirc.template
.python-version		.python-version
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
ERROR_HANDLING.md		ERROR_HANDLING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
QUICK_FIX.md		QUICK_FIX.md
README.md		README.md
RELEASE_GUIDE.md		RELEASE_GUIDE.md
build.spec		build.spec
context7-installation-analysis.md		context7-installation-analysis.md
pyproject.toml		pyproject.toml
setup.py		setup.py
uv.lock		uv.lock

License

adamsmaka/flutter-mcp

Folders and files

Latest commit

History

Repository files navigation

Flutter MCP: Give Your AI Real-Time Flutter Superpowers 🚀

🎬 Demo

The Problem: Your AI is Stuck in 2021

😡 Without Flutter MCP

✅ With Flutter MCP

🚀 Quick Start

Installation

Alternative Installation Methods

Requirements

2. Add to Your AI Assistant

3. Start the Server (Optional for Testing)

3. Use It!

🎯 New Simplified Usage (Recommended)

💫 Natural Language Support

🔧 Legacy Support

🎯 Version-Specific Documentation (NEW!)

📚 Available Tools

🎯 NEW: Simplified Tools (Context7-style)

1. flutter_search - Universal Search

2. flutter_docs - Smart Documentation Fetcher

3. flutter_status - Health Check (Optional)

📦 Legacy Tools (Deprecated but still functional)

get_flutter_docs (Use flutter_docs instead)

get_pub_package_info (Use flutter_docs instead)

search_flutter_docs (Use flutter_search instead)

process_flutter_mentions (Still functional)

health_check (Use flutter_status instead)

🎯 Features

💡 How It Works

The Magic Behind the Scenes

Performance Notes

Error Handling

📊 What Gets Indexed

🛠️ Advanced Usage

🛠️ Troubleshooting

📱 Client Configurations

🤝 Contributing

Quick Ways to Contribute

🚀 What's New & Coming Soon

❤️ Spread the Word

📄 License

🏗️ Built With

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages