{"id":48236013,"url":"https://github.com/mimen/beeper-mcp","last_synced_at":"2026-04-26T11:03:50.034Z","repository":{"id":352557378,"uuid":"1038368844","full_name":"mimen/beeper-mcp","owner":"mimen","description":"MCP server for accessing Beeper chat conversations","archived":false,"fork":false,"pushed_at":"2025-08-15T04:24:06.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-20T07:02:46.438Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mimen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-15T04:24:04.000Z","updated_at":"2025-08-15T04:24:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mimen/beeper-mcp","commit_stats":null,"previous_names":["mimen/beeper-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mimen/beeper-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimen%2Fbeeper-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimen%2Fbeeper-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimen%2Fbeeper-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimen%2Fbeeper-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mimen","download_url":"https://codeload.github.com/mimen/beeper-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimen%2Fbeeper-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32294592,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T20:00:26.649Z","updated_at":"2026-04-26T11:03:50.023Z","avatar_url":"https://github.com/mimen.png","language":"Python","funding_links":[],"categories":["🤖 MCP Servers"],"sub_categories":[],"readme":"# Beeper MCP Server\n\nA 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.\n\n## Features\n\n- **Read-only access** to local Beeper SQLite and IndexedDB (LevelDB) databases\n- **Auto-discovery** of Beeper databases in common macOS locations\n- **Dual storage format support**: SQLite and IndexedDB/LevelDB\n- **Cross-version compatibility** with different Beeper/Element database schemas\n- **Three MCP tools**:\n  - `list_conversations`: View recent conversations with metadata\n  - `read_messages`: Read messages from specific conversations\n  - `search_messages`: Search across all message content\n- **Privacy-focused**: No network requests, no data persistence, local-only operation\n- **Security**: SQL injection protection, read-only database connections\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.8 or higher\n- Beeper desktop app installed on macOS\n- Claude Desktop (for integration)\n- For IndexedDB support: LevelDB libraries (install with `brew install leveldb`)\n\n### Installation\n\n1. Clone this repository:\n```bash\ngit clone https://github.com/yourusername/beeper-mcp-server.git\ncd beeper-mcp-server\n```\n\n2. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n3. Test the server:\n```bash\npython main.py\n```\n\nThe server should start and display: `Starting Beeper MCP server...`\n\nPress Ctrl+C to stop.\n\n### Claude Desktop Integration\n\n1. Open Claude Desktop settings\n2. Navigate to Developer → Model Context Protocol\n3. Add a new MCP server with the following configuration:\n\n```json\n{\n  \"beeper\": {\n    \"command\": \"python\",\n    \"args\": [\"/path/to/beeper-mcp-server/main.py\"]\n  }\n}\n```\n\nReplace `/path/to/beeper-mcp-server` with the actual path where you cloned this repository.\n\n4. Restart Claude Desktop\n5. Look for the 🔌 icon to confirm the server is connected\n\n## Usage Examples\n\nOnce integrated with Claude Desktop, you can use these commands:\n\n### List Recent Conversations\nAsk Claude: \"Use the beeper tool to list my recent conversations\"\n\n### Read Messages from a Conversation\nAsk Claude: \"Read the last 20 messages from conversation [conversation_id]\"\n\n### Search Messages\nAsk Claude: \"Search my Beeper messages for 'meeting tomorrow'\"\n\n## Configuration\n\nThe server uses `config.json` for configuration. Default settings:\n\n```json\n{\n  \"database_paths\": [\n    \"~/Library/Application Support/Beeper\",\n    \"~/Library/Application Support/Beeper/IndexedDB\",\n    \"~/.config/Beeper\",\n    \"~/Library/Application Support/Element\",\n    \"~/.config/Element\"\n  ],\n  \"max_results\": 50,\n  \"log_level\": \"INFO\"\n}\n```\n\n### Custom Database Paths\n\nIf Beeper is installed in a non-standard location, add the path to `database_paths` in `config.json`.\n\n### Environment Variables\n\nYou can also set database paths via environment variable:\n```bash\nexport BEEPER_DB_PATH=\"/custom/path/to/beeper\"\npython main.py\n```\n\n## Troubleshooting\n\n### Server won't start\n- Ensure Python 3.8+ is installed: `python --version`\n- Check that all dependencies are installed: `pip install -r requirements.txt`\n- Verify the file has execute permissions: `chmod +x main.py`\n\n### No conversations found\n- Ensure Beeper desktop app has been used and has message history\n- Check that Beeper is installed in one of the default locations\n- Try adding your Beeper installation path to `config.json`\n- Check logs for database discovery details\n- For IndexedDB: Look for `.indexeddb.leveldb` directories in Application Support\n\n### Permission errors\n- The server only needs read access to Beeper databases\n- On macOS, you may need to grant terminal/Python disk access in System Preferences → Security \u0026 Privacy\n\n### Database not found\nRun the test script to check database discovery:\n```bash\npython test_server.py\n```\n\n## Testing\n\nRun the included test utilities:\n\n```bash\n# Test database discovery\npython test_server.py --discover\n\n# Test with sample data\npython test_server.py --sample\n\n# Full integration test\npython test_server.py --full\n```\n\n## Security Notes\n\n- **Read-only**: All database connections are read-only\n- **Local only**: No network requests or external communication\n- **No persistence**: No data is cached or stored\n- **Input validation**: All user inputs are validated and parameterized\n- **SQL injection protection**: Uses parameterized queries throughout\n\n## Development\n\n### Project Structure\n```\nbeeper-mcp-server/\n├── main.py              # MCP server entry point\n├── beeper_reader.py     # Database access logic\n├── requirements.txt     # Python dependencies\n├── config.json         # Configuration\n├── README.md           # This file\n└── test_server.py      # Testing utilities\n```\n\n### Adding New Features\n\n1. Database queries: Add to `beeper_reader.py`\n2. New MCP tools: Register in `main.py`\n3. Configuration options: Update `config.json` and `_load_config()`\n\n### Debugging\n\nEnable debug logging:\n```json\n{\n  \"log_level\": \"DEBUG\"\n}\n```\n\nOr via command line:\n```bash\npython main.py --debug\n```\n\n## Known Limitations\n\n- macOS only (uses macOS-specific paths)\n- Read-only access (by design)\n- Limited to local Beeper installations\n- Message formatting may vary by Beeper version\n- IndexedDB support requires plyvel library and system LevelDB installation\n\n## Contributing\n\nPull requests welcome! Please:\n- Maintain read-only operation\n- Add tests for new features\n- Update documentation\n- Follow existing code style\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Support\n\nFor issues or questions:\n- Check troubleshooting section above\n- Review debug logs\n- Open an issue on GitHub","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmimen%2Fbeeper-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmimen%2Fbeeper-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmimen%2Fbeeper-mcp/lists"}