Provides read-only access to local Element message databases on macOS, allowing users to search conversations, read messages, and list recent chats from their Element desktop app data
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:
Install dependencies:
Test the server:
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:
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:
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:
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:
Testing
Run the included test utilities:
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
Adding New Features
Database queries: Add to
beeper_reader.py
New MCP tools: Register in
main.py
Configuration options: Update
config.json
and_load_config()
Debugging
Enable debug logging:
Or via command line:
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
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Provides read-only access to local Beeper message history on macOS, enabling users to search conversations, read messages, and list recent chats through natural language queries. Supports both SQLite and IndexedDB storage formats with privacy-focused local-only operation.
Related MCP Servers
- -securityAlicense-qualityAllows the AI to read from your local Apple Notes database (macOS only)Last updated -119MIT License
- AsecurityFlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with Apple Reminders on macOS, allowing users to view lists, retrieve, create, complete, and delete reminders through natural language.Last updated -56
- -securityFlicense-qualityA Python server that enables interaction with macOS native applications (Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps) through AppleScript, featuring asynchronous operations and type-safe interfaces.Last updated -13
- AsecurityAlicenseAqualityProvides advanced system monitoring and file search capabilities for macOS, allowing users to track performance metrics and perform enhanced file searches with content analysis and tagging features.Last updated -21314MIT License