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.

🎬 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

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

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

1. MCP Integration: Your AI assistant automatically detects when you're asking about Flutter/Dart packages
2. Smart Detection: No special syntax required - just mention package names naturally
3. Lightning Cache: First request fetches from pub.dev (1-2 seconds), subsequent requests are instant
4. Context Injection: Documentation is seamlessly added to your AI's knowledge before it responds
5. 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

🤝 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

MIT © 2024 Flutter MCP Contributors

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

🚀 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

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

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

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

# 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

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.

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.

In Settings → MCP Servers, add:

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

MCP SuperAssistant requires HTTP transport. Configure it with:

1. Start the server with HTTP transport:

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

2. In MCP SuperAssistant, add a new server:

   • Name: Flutter MCP
   • URL: http://localhost:8000
   • Type: HTTP MCP Server

3. The server will now be available in your MCP SuperAssistant client.

In your .continuerc.json:

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

3. Start the Server (Optional for Testing)

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

🛠️ Advanced Usage

# 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).

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

📱 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

🛠️ Troubleshooting

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

1. Use npx (recommended):

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

2. Install globally first:

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

3. Check Node.js installation:

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

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

• 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

Different MCP clients require different transport protocols:

1. Claude Desktop: Uses STDIO transport (default)

   • No port/URL needed
   • Just use: npx flutter-mcp

2. MCP SuperAssistant: Requires HTTP transport

   • Start with: npx flutter-mcp --transport http --port 8000
   • Connect to: http://localhost:8000

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