firefox-mcp

# Firefox MCP Server A Model Context Protocol (MCP) server that provides tools for accessing and analyzing Firefox browser data including browsing history, bookmarks, and other browser information. ## Features - **History Retrieval**: Query Firefox browsing history with advanced filtering - **Profile Discovery**: Automatically detect and manage Firefox profiles - **Data Export**: Export browser data in multiple formats (JSON, JSONL, CSV) - **Performance Optimized**: Handles large datasets (100k+ entries) efficiently - **Cross-Platform**: Works on Windows, macOS, and Linux - **Security First**: Read-only access with SQL injection protection ## Installation ```bash npm install npm run build ``` ## Usage ### As MCP Server Start the server to expose tools via MCP protocol: ```bash npm start ``` ### Available Tools #### `get_firefox_history` Retrieve Firefox browsing history with filtering and pagination. Parameters: - `profile` (optional): Firefox profile name - `startDate` (optional): Start date in ISO format - `endDate` (optional): End date in ISO format - `urlPattern` (optional): URL pattern to search for - `domain` (optional): Domain to filter by - `limit` (optional): Maximum results (default: 100, max: 10000) - `offset` (optional): Results to skip for pagination - `sortBy` (optional): Sort field ('visitTime', 'url', 'title', 'visitCount') - `sortOrder` (optional): Sort direction ('asc', 'desc') - `excludeHidden` (optional): Exclude hidden entries (default: true) - `onlyTyped` (optional): Only manually typed URLs (default: false) #### `get_firefox_history_count` Get history statistics and counts by domain/date. Parameters: - `profile` (optional): Firefox profile name - `startDate` (optional): Start date filter - `endDate` (optional): End date filter - `urlPattern` (optional): URL pattern filter - `domain` (optional): Domain filter #### `export_firefox_history` Export history data in various formats. Parameters: - `profile` (optional): Firefox profile name - `format` (optional): Export format ('json', 'jsonl', 'csv') - `startDate` (optional): Start date filter - `endDate` (optional): End date filter - `urlPattern` (optional): URL pattern filter - `domain` (optional): Domain filter - `outputPath` (optional): File path to save export #### `get_firefox_profiles` List all available Firefox profiles on the system. ## Architecture ### Core Components - **DatabaseConnectionManager**: Manages SQLite connections with locking detection - **FirefoxSchemaHandler**: Handles different Firefox database schema versions - **HistoryQueryBuilder**: Provides SQL injection protection and query optimization - **OptimizedQueryEngine**: Includes caching and performance monitoring - **StreamingExporter**: Memory-efficient data export - **FirefoxProfileDiscovery**: Cross-platform profile detection ### Security Features - Read-only database access - SQL injection prevention through parameterized queries - Database lock detection and retry logic - Input validation with Zod schemas - Safe profile path resolution ### Performance Features - Cursor-based pagination for large datasets - Query result caching - Prepared statement optimization - Streaming exports for memory efficiency - Database index utilization ## Testing Run the test suite: ```bash npm test ``` Run performance tests: ```bash npm test -- --testNamePattern="Performance Tests" ``` ## Development ### Building ```bash npm run build ``` ### Type Checking ```bash npm run typecheck ``` ### Linting ```bash npm run lint ``` ## Firefox Profile Locations The server automatically detects Firefox profiles in standard locations: - **Windows**: `%APPDATA%\\Mozilla\\Firefox\\Profiles` - **macOS**: `~/Library/Application Support/Firefox/Profiles` - **Linux**: `~/.mozilla/firefox` ## Database Schema Support Supports Firefox database schema versions 60+ with automatic version detection and compatibility handling. ## Limitations - Read-only access (cannot modify Firefox data) - May have limited access to very recent history when Firefox is running - Performance depends on Firefox database size and system resources ## License MIT License - see LICENSE file for details. ## Contributing 1. Fork the repository 2. Create a feature branch 3. Add tests for new functionality 4. Ensure all tests pass 5. Submit a pull request ## Security Notes This tool accesses Firefox's SQLite databases directly. While all operations are read-only and include safety measures: - Always backup your Firefox profile before running any browser data tools - The tool respects database locks and will not corrupt your Firefox data - All database queries use parameterized statements to prevent SQL injection - Profile discovery only accesses standard Firefox configuration files ## Support For issues and questions, please use the GitHub issue tracker.