mimen/beeper-mcp

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:

git clone https://github.com/yourusername/beeper-mcp-server.git
cd beeper-mcp-server

2. Install dependencies:

pip install -r requirements.txt

3. Test the server:

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:

{
  "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:

{
  "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.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:

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

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:

{
  "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