https://github.com/mimen/beeper-mcp
MCP server for accessing Beeper chat conversations
https://github.com/mimen/beeper-mcp
Last synced: about 2 months ago
JSON representation
MCP server for accessing Beeper chat conversations
- Host: GitHub
- URL: https://github.com/mimen/beeper-mcp
- Owner: mimen
- Created: 2025-08-15T04:24:04.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-08-15T04:24:06.000Z (10 months ago)
- Last Synced: 2026-04-20T07:02:46.438Z (about 2 months ago)
- Language: Python
- Size: 13.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-beeper - beeper-mcp
README
# 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