Skip to main content
Glama

Beeper MCP Server

by mimen
GitHub
Python
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

  1. Install dependencies:

pip install -r requirements.txt

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

  1. Restart Claude Desktop

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

This server cannot be installed

-
security - not tested
F
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.

  1. Features
    1. Quick Start
      1. Prerequisites
      2. Installation
      3. Claude Desktop Integration
    2. Usage Examples
      1. List Recent Conversations
      2. Read Messages from a Conversation
      3. Search Messages
    3. Configuration
      1. Custom Database Paths
      2. Environment Variables
    4. Troubleshooting
      1. Server won't start
      2. No conversations found
      3. Permission errors
      4. Database not found
    5. Testing
      1. Security Notes
        1. Development
          1. Project Structure
          2. Adding New Features
          3. Debugging
        2. Known Limitations
          1. Contributing
            1. License
              1. Support

                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 -
                  119
                  MIT License
                  • Apple

                • 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
                  6
                  • Apple

                • 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 -
                  13
                  • Apple

                • macOS Tools MCP Server

                  tornikegomareli
                  A
                  security
                  A
                  license
                  A
                  quality
                  Provides 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 -
                  2
                  13
                  14
                  MIT License
                  • Apple

                View all related MCP servers

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/mimen/beeper-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server