Beeper MCP Server

# Beeper MCP Server A Model Context Protocol (MCP) server that provides read-only access to Beeper messages on macOS. This server allows Claude Desktop and other MCP clients to search and read your local Beeper message history. ## Features - **Read-only access** to local Beeper SQLite and IndexedDB (LevelDB) databases - **Auto-discovery** of Beeper databases in common macOS locations - **Dual storage format support**: SQLite and IndexedDB/LevelDB - **Cross-version compatibility** with different Beeper/Element database schemas - **Three MCP tools**: - `list_conversations`: View recent conversations with metadata - `read_messages`: Read messages from specific conversations - `search_messages`: Search across all message content - **Privacy-focused**: No network requests, no data persistence, local-only operation - **Security**: SQL injection protection, read-only database connections ## Quick Start ### Prerequisites - Python 3.8 or higher - Beeper desktop app installed on macOS - Claude Desktop (for integration) - For IndexedDB support: LevelDB libraries (install with `brew install leveldb`) ### Installation 1. Clone this repository: ```bash git clone https://github.com/yourusername/beeper-mcp-server.git cd beeper-mcp-server ``` 2. Install dependencies: ```bash pip install -r requirements.txt ``` 3. Test the server: ```bash python main.py ``` The server should start and display: `Starting Beeper MCP server...` Press Ctrl+C to stop. ### Claude Desktop Integration 1. Open Claude Desktop settings 2. Navigate to Developer → Model Context Protocol 3. Add a new MCP server with the following configuration: ```json { "beeper": { "command": "python", "args": ["/path/to/beeper-mcp-server/main.py"] } } ``` Replace `/path/to/beeper-mcp-server` with the actual path where you cloned this repository. 4. Restart Claude Desktop 5. Look for the 🔌 icon to confirm the server is connected ## Usage Examples Once integrated with Claude Desktop, you can use these commands: ### List Recent Conversations Ask Claude: "Use the beeper tool to list my recent conversations" ### Read Messages from a Conversation Ask Claude: "Read the last 20 messages from conversation [conversation_id]" ### Search Messages Ask Claude: "Search my Beeper messages for 'meeting tomorrow'" ## Configuration The server uses `config.json` for configuration. Default settings: ```json { "database_paths": [ "~/Library/Application Support/Beeper", "~/Library/Application Support/Beeper/IndexedDB", "~/.config/Beeper", "~/Library/Application Support/Element", "~/.config/Element" ], "max_results": 50, "log_level": "INFO" } ``` ### Custom Database Paths If Beeper is installed in a non-standard location, add the path to `database_paths` in `config.json`. ### Environment Variables You can also set database paths via environment variable: ```bash export BEEPER_DB_PATH="/custom/path/to/beeper" python main.py ``` ## Troubleshooting ### Server won't start - Ensure Python 3.8+ is installed: `python --version` - Check that all dependencies are installed: `pip install -r requirements.txt` - Verify the file has execute permissions: `chmod +x main.py` ### No conversations found - Ensure Beeper desktop app has been used and has message history - Check that Beeper is installed in one of the default locations - Try adding your Beeper installation path to `config.json` - Check logs for database discovery details - For IndexedDB: Look for `.indexeddb.leveldb` directories in Application Support ### Permission errors - The server only needs read access to Beeper databases - On macOS, you may need to grant terminal/Python disk access in System Preferences → Security & Privacy ### Database not found Run the test script to check database discovery: ```bash python test_server.py ``` ## Testing Run the included test utilities: ```bash # Test database discovery python test_server.py --discover # Test with sample data python test_server.py --sample # Full integration test python test_server.py --full ``` ## Security Notes - **Read-only**: All database connections are read-only - **Local only**: No network requests or external communication - **No persistence**: No data is cached or stored - **Input validation**: All user inputs are validated and parameterized - **SQL injection protection**: Uses parameterized queries throughout ## Development ### Project Structure ``` beeper-mcp-server/ ├── main.py # MCP server entry point ├── beeper_reader.py # Database access logic ├── requirements.txt # Python dependencies ├── config.json # Configuration ├── README.md # This file └── test_server.py # Testing utilities ``` ### Adding New Features 1. Database queries: Add to `beeper_reader.py` 2. New MCP tools: Register in `main.py` 3. Configuration options: Update `config.json` and `_load_config()` ### Debugging Enable debug logging: ```json { "log_level": "DEBUG" } ``` Or via command line: ```bash python main.py --debug ``` ## Known Limitations - macOS only (uses macOS-specific paths) - Read-only access (by design) - Limited to local Beeper installations - Message formatting may vary by Beeper version - IndexedDB support requires plyvel library and system LevelDB installation ## Contributing Pull requests welcome! Please: - Maintain read-only operation - Add tests for new features - Update documentation - Follow existing code style ## License MIT License - see LICENSE file for details ## Support For issues or questions: - Check troubleshooting section above - Review debug logs - Open an issue on GitHub