mcp-crashlytics-server

# 🔥 Firebase Crashlytics MCP Server [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://modelcontextprotocol.io/) A clean, simple **Model Context Protocol (MCP)** server that integrates Firebase Crashlytics with BigQuery for AI-powered crash analysis. Built for use with Claude Code and other MCP-compatible AI assistants. ## ✨ Features - 🔍 **Simple Tools**: Clean, single-responsibility tools for crash analysis - 📱 **App Discovery**: Automatically discover all apps in your Firebase project - 💥 **Fatal Crash Analysis**: Get detailed fatal crashes with stack traces - 🐛 **ANR Issue Detection**: Analyze Application Not Responding issues - 🔧 **Easy Setup**: Simple configuration with environment variables - 🤖 **AI-Optimized**: Structured output perfect for AI analysis and debugging ## 🚀 Quick Start ### Prerequisites - Node.js 18+ - Firebase project with Crashlytics enabled - BigQuery export enabled for Crashlytics - Google Cloud service account with BigQuery access ### Installation 1. **Clone the repository:** ```bash git clone https://github.com/your-username/mcp-crashlytics-server.git cd mcp-crashlytics-server ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Build the project:** ```bash npm run build ``` ### Configuration 1. **Create environment file:** ```bash cp .env.example .env ``` 2. **Configure your environment variables:** ```bash # Google Cloud Service Account (choose one method) GOOGLE_SERVICE_ACCOUNT_KEY=/path/to/your-service-account.json # OR base64-encoded: GOOGLE_SERVICE_ACCOUNT_KEY=eyJhbGciOiJIUzI1... # Your Firebase project settings BIGQUERY_PROJECT_ID=your-firebase-project-id BIGQUERY_DATASET_ID=firebase_crashlytics # Optional: Default limit for crash queries DEFAULT_CRASH_LIMIT=10 ``` ### Setup Firebase & BigQuery 1. **Enable Crashlytics BigQuery Export:** - Go to Firebase Console → Project Settings → Integrations - Enable BigQuery integration for Crashlytics - Data will be exported to `firebase_crashlytics` dataset 2. **Create Service Account:** - Go to [Google Cloud Console](https://console.cloud.google.com/) - Navigate to IAM & Admin → Service Accounts - Create service account with these roles: - `BigQuery Data Viewer` - `BigQuery Job User` - Download JSON key file ### Register with AI Agents #### Claude Code ```bash # Register the MCP server claude mcp add crashlytics -- node /path/to/mcp-crashlytics-server/dist/index.js # Verify it's working claude mcp list ``` #### Cursor Add to your `.cursorrules` or cursor settings: ```json { "mcpServers": { "crashlytics": { "command": "node", "args": ["/path/to/mcp-crashlytics-server/dist/index.js"], "env": { "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/your-service-account.json", "BIGQUERY_PROJECT_ID": "your-firebase-project-id", "BIGQUERY_DATASET_ID": "firebase_crashlytics" } } } } ``` #### Windsurf Add to your Windsurf settings or `.windsurfrules`: ```json { "mcp": { "servers": { "crashlytics": { "command": "node", "args": ["/path/to/mcp-crashlytics-server/dist/index.js"], "env": { "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/your-service-account.json", "BIGQUERY_PROJECT_ID": "your-firebase-project-id", "BIGQUERY_DATASET_ID": "firebase_crashlytics" } } } } } ``` #### Other MCP-Compatible IDEs For other MCP-compatible tools, add this server configuration: - **Command**: `node` - **Args**: `["/path/to/mcp-crashlytics-server/dist/index.js"]` - **Environment Variables**: Same as above (.env file values) ## 🛠️ Available Tools ### 1. `list_available_apps` **Discover all apps** in your Firebase Crashlytics dataset. - **Parameters**: None - **Returns**: List of apps with crash counts ```javascript // Usage in Claude Code/Cursor "What apps are available in my crashlytics data?" ``` ### 2. `get_fatal_crashes` **Get fatal crashes** for a specific app. - **Parameters**: - `app_package` (required): App package name (e.g., "com.example.myapp") - `limit` (optional): Number of crashes (1-50, default: 10) ```javascript // Usage in Claude Code/Cursor "Get the 10 most recent fatal crashes for com.example.myapp" ``` ### 3. `get_anr_issues` **Get ANR (Application Not Responding)** issues for a specific app. - **Parameters**: - `app_package` (required): App package name - `limit` (optional): Number of issues (1-50, default: 10) ```javascript // Usage in Claude Code/Cursor "Show me ANR issues for com.example.myapp, limit to 5" ``` ## 📋 Example Usage Once set up, you can ask Claude Code natural questions like: ```bash # Discover your apps "What apps do I have crash data for?" # Get fatal crashes "Show me the latest fatal crashes for my Android app" "Get 5 fatal crashes for com.mycompany.myapp" # Analyze ANR issues "What ANR issues does my app have?" "Show ANR problems for com.mycompany.myapp from the last week" ``` ## 🏗️ Project Structure ``` mcp-crashlytics-server/ ├── src/ │ ├── index.ts # Main MCP server │ ├── bigquery-client.ts # BigQuery integration │ ├── crash-processor.ts # Crash data processing │ ├── impact-analyzer.ts # Impact analysis │ └── types.ts # TypeScript definitions ├── dist/ # Built JavaScript files ├── package.json ├── tsconfig.json ├── .env.example # Environment template └── README.md ``` ## 🔧 Development ### Running in Development Mode ```bash npm run dev ``` ### Building ```bash npm run build ``` ### Linting ```bash npm run lint ``` ### Testing ```bash npm test ``` ## 🐛 Troubleshooting ### Common Issues **1. "No MCP servers configured"** - Make sure to register the server: `claude mcp add crashlytics -- node /path/to/dist/index.js` - Restart Claude Code/Cursor IDE **2. "Authentication Failed"** - Verify service account JSON file path is correct - Ensure service account has BigQuery permissions - Check project ID matches your Firebase project **3. "No crashes returned"** - Confirm Crashlytics BigQuery export is enabled - Wait 24-48 hours for initial data export - Verify your app is actually sending crash data **4. "Table not found"** - Check that `BIGQUERY_DATASET_ID` is correct (usually `firebase_crashlytics`) - Ensure crashes exist in your Firebase project - Verify BigQuery export is working in Firebase Console ### Debug Mode Enable verbose logging: ```bash DEBUG=mcp-crashlytics-server npm start ``` ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Make your changes 4. Add tests for new functionality 5. Commit your changes (`git commit -m 'Add amazing feature'`) 6. Push to the branch (`git push origin feature/amazing-feature`) 7. Open a Pull Request ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🔒 Security Considerations - ⚠️ **Never expose service account credentials** in logs or version control - 🔐 Use **least-privilege permissions** for service accounts - 🔑 Store credentials securely using environment variables - 🚫 Add `.env` to `.gitignore` (already included) ## 📚 Resources - [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) - [Firebase Crashlytics](https://firebase.google.com/products/crashlytics) - [BigQuery Documentation](https://cloud.google.com/bigquery/docs) ## 💡 Need Help? - 🐛 **Found a bug?** [Open an issue](https://github.com/your-username/mcp-crashlytics-server/issues) - 💬 **Have questions?** [Start a discussion](https://github.com/your-username/mcp-crashlytics-server/discussions) - 🚀 **Want a feature?** [Request it here](https://github.com/your-username/mcp-crashlytics-server/issues/new?template=feature_request.md) --- **Made with ❤️ for the MCP community**