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 metadataread_messages: Read messages from specific conversationssearch_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
- Clone this repository:
git clone https://github.com/yourusername/beeper-mcp-server.git
cd beeper-mcp-server
- Install dependencies:
pip install -r requirements.txt
- Test the server:
python main.py
The server should start and display: Starting Beeper MCP server...
Press Ctrl+C to stop.
Claude Desktop Integration
- Open Claude Desktop settings
- Navigate to Developer → Model Context Protocol
- Add a new MCP server with the following configuration:
{
"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.
- Restart Claude Desktop
- 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:
{
"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:
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.leveldbdirectories 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:
python test_server.py
Testing
Run the included test utilities:
# 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
- Database queries: Add to
beeper_reader.py - New MCP tools: Register in
main.py - Configuration options: Update
config.jsonand_load_config()
Debugging
Enable debug logging:
{
"log_level": "DEBUG"
}
Or via command line:
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