flutter-mcp

A stdio Model Context Protocol server that helps AI assistants understand Flutter and Dart codebases quickly.

flutter-mcp is designed for local AI coding agents. It scans a Flutter project with pure TypeScript and Node.js, no Dart SDK required, then returns summary-first context that an AI can use to reason about architecture, files, symbols, routes, relationships, and hotspots.

Install

npm install -g @raheesahmed37/flutter-mcp

For local development from this repository:

npm install
npm run build
node dist/index.js --project D:\path\to\flutter_app

MCP Configuration

Use the published package:

{
  "mcpServers": {
    "flutter-mcp": {
      "command": "npx",
      "args": ["@raheesahmed37/flutter-mcp", "--project", "D:\\path\\to\\flutter_app"]
    }
  }
}

Use a local checkout:

{
  "mcpServers": {
    "flutter-mcp": {
      "command": "node",
      "args": ["D:\\mcp-servers\\flutter-mcp\\dist\\index.js", "--project", "D:\\path\\to\\flutter_app"]
    }
  }
}

Tools

The public MCP surface is intentionally small: five strong tools instead of many narrow tools.

get_project_info

Parses pubspec.yaml and pubspec.lock.

Returns:

• app name and description
• Dart SDK constraints
• dependencies and resolved versions
• detected packages such as BLoC, Provider, Riverpod, GetX, Hive, Dio, Firebase, Freezed, and build_runner
• plain-English project summary

get_repo_map

Builds a clean AI-readable repository map.

Returns:

• annotated file tree
• Dart/generated file counts
• feature/group summary
• important files to read first
• largest files
• warnings for large files and circular imports

Generated files and noisy folders such as .git, .dart_tool, .gradle, .idea, .next, Pods, build, and binary assets are skipped by default.

read_context

Reads context by file, topic, or symbol.

Examples:

{ "project_path": "D:\\app", "file_path": "lib/main.dart", "start_line": 1, "end_line": 80 }

{ "project_path": "D:\\app", "topic": "auth", "max_files": 8 }

{ "project_path": "D:\\app", "symbol": "LoginScreen" }

Returns:

• file content or topic context pack
• related imports and dependents
• symbols found in context files
• important files
• recommended next tools

search_code

Searches Dart code with multiple modes.

Modes:

• text
• symbol
• route
• widget
• dependency

Examples:

{ "project_path": "D:\\app", "query": "GeminiService", "mode": "symbol" }

{ "project_path": "D:\\app", "query": "/login", "mode": "route" }

analyze_project

The main AI understanding tool.

Focus modes:

• full
• architecture
• state_management
• navigation
• data_flow
• testing
• hotspots

Returns:

• pattern report
• feature map
• route map
• symbol counts
• import graph hotspots
• circular imports
• warnings
• important files
• recommended next tools

Recommended AI Workflow

1. Call get_project_info to identify the stack.
2. Call get_repo_map to understand layout and important files.
3. Call analyze_project with focus: "full" for architecture, routes, state, and hotspots.
4. Call read_context for the feature, file, or symbol being changed.
5. Use search_code for targeted lookup.

Design Goals

• stdio only
• npm installable
• no Dart SDK required
• zero shell execution against the target project
• summary-first JSON responses
• relative paths in responses
• generated/noisy files skipped by default
• resilient parsing for incomplete or malformed Dart files
• useful for any AI coding assistant, not just one client

Development

npm install
npm test
npm run build

The test suite uses Node's built-in test runner with tsx.

Current Parser Strategy

The parser is regex-based by design. It extracts enough structure for AI code understanding without requiring Flutter, Dart, or analyzer binaries to be installed.

It detects:

• classes
• stateless and stateful widgets
• enums, mixins, extensions
• Riverpod providers
• BLoC/Cubit classes
• imports
• widget dependencies
• common project patterns
• routes and Navigator usage

License

MIT