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

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.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

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:

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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

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

apple-notes-mcp
sirmews
-
security
A
license
-
quality
Allows the AI to read from your local Apple Notes database (macOS only)
Last updated -
116
Python
MIT License
iMessage MCP Server
marissamarym
A
security
F
license
A
quality
A local server that enables Claude Desktop to interact with your macOS Contacts and Messages apps, allowing you to search contacts and send iMessages through natural language commands.
Last updated -
2
14
JavaScript
MCP Apple Reminders
shadowfax92
A
security
F
license
A
quality
A 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 -
5
5
TypeScript
Python Apple MCP
jxnl
-
security
F
license
-
quality
A 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 -
12
Python

View all related MCP servers

Beeper MCP Server