# π‘οΈ Heimdall MCP Server βοΈ
## π **[Visit Official Website](https://heimdall-mcp-v02.vercel.app)** | [Documentation](docs/) | [GitHub](https://github.com/sarva-20/heimdall-mcp)
---
[](https://github.com/sarva-20/heimdall-mcp/releases)
[](https://modelcontextprotocol.io)
[](https://mcpservers.org)
[](https://www.apple.com/macos/)
[](https://bun.sh)
[](LICENSE)
[](SECURITY.md)
**"The all-seeing guardian of the BifrΓΆst."**
Heimdall bridges Claude Desktop and your macOS system, giving AI the power to monitor hardware, control applications, and interact with your workflow.
**[π¦ Latest Release](https://github.com/sarva-20/heimdall-mcp/releases) β’ [π Documentation](docs/INSTALLATION.md) β’ [π Report Bug](https://github.com/sarva-20/heimdall-mcp/issues)**
---
## β¨ Features
| Feature | Description |
|---------|-------------|
| ποΈ **Vision** | Take screenshots and see your screen |
| π **Voice** | Text-to-speech for audio feedback |
| π **Monitoring** | Battery, CPU, and RAM metrics |
| π» **System Info** | OS details, CPU specs, hostname |
| π **Clipboard** | Read and write clipboard content |
| π **Files** | Save files directly to Desktop |
| π **App Control** | Launch, quit, and list applications |
---
---
## π Repository Structure
This monorepo contains:
- **`/src`** - Heimdall MCP Server (TypeScript)
- **`/website`** - Official React landing page
- **`/docs`** - Complete documentation
### π Website
Our landing page is built with React + Vite + Tailwind and deployed on Vercel.
**Live at:** [heimdall-mcp-v02.vercel.app](https://heimdall-mcp-v02.vercel.app)
To run locally:
```bash
cd website
npm install
npm run dev
```
---
## π Quick Start
```bash
# Clone and install
git clone https://github.com/sarva-20/heimdall-mcp.git
cd heimdall-mcp
bun install
# Configure (see Installation Guide)
open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
**Full setup guide:** [π Installation](docs/INSTALLATION.md)
---
## π¬ Demo
**π [Interactive Demo on Our Website](https://heimdall-mcp-v02.vercel.app)** - Try Heimdall commands in your browser!
See live examples, explore features, and test the interactive playground.
### Example Commands
```
"Check my battery levels"
"Launch Spotify"
"What apps are running?"
"Read my clipboard and explain the error"
"Save this code to my desktop as script.py"
```
---
## π Documentation
- **[Installation Guide](docs/INSTALLATION.md)** - Complete setup instructions
- **[Usage Guide](docs/USAGE.md)** - Examples and commands
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and fixes
- **[Contributing](docs/CONTRIBUTING.md)** - How to contribute
- **[Changelog](CHANGELOG.md)** - Version history
---
## π οΈ Available Tools
### System Monitoring
- `get_battery` - Battery status with time remaining
- `get_cpu_load` - Current CPU usage
- `get_memory_usage` - RAM usage with percentage
- `get_system_info` - OS, CPU, and hostname
### System Actions
- `speak_message` - Text-to-speech output
- `take_screenshot` - Capture screen (requires permission)
### Clipboard & Files
- `read_clipboard` - Read clipboard content
- `write_to_clipboard` - Copy text to clipboard
- `save_to_desktop` - Save files to Desktop
### Application Control
- `launch_application` - Open macOS apps
- `quit_application` - Close running apps
- `list_running_apps` - List all running apps
---
## π§° Requirements
- **macOS** (Apple Silicon or Intel)
- **Bun** runtime ([Install](https://bun.sh))
- **Claude Desktop** ([Download](https://claude.ai/download))
---
## ποΈ Roadmap
### v0.2 - Media & Productivity β
**Released**
- π΅ Spotify advanced controls (play, pause, skip, playlists)
- πͺ Window management (focus, minimize, list)
- π΅ Get currently playing track
- π¨ System control (volume, brightness, dark mode)
### v0.3 - Smart Notifications
- π System notifications and scheduled reminders
- π Enhanced file operations (read, search)
### v0.4 - System Control
- π¨ Brightness and volume control
- π Browser integration
- π Lock screen and sleep commands
[View Full Roadmap](CHANGELOG.md#unreleased)
---
## π¦ Installation
### Quick Install
```bash
git clone https://github.com/sarva-20/heimdall-mcp.git
cd heimdall-mcp
bun install
```
### Configure Claude Desktop
Find your paths:
```bash
which bun # Get Bun path
pwd # Get Heimdall path
```
Edit config:
```bash
open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
Add:
```json
{
"mcpServers": {
"heimdall-mcp": {
"command": "/path/to/bun",
"args": ["run", "/path/to/heimdall-mcp/index.ts"]
}
}
}
```
Restart Claude Desktop (`Cmd + Q`).
**Detailed instructions:** [Installation Guide](docs/INSTALLATION.md)
---
## π License
MIT License - see [LICENSE](LICENSE) for details.
---
## π Acknowledgments
-
- ## π Security
-
- See [SECURITY.md](SECURITY.md) for our security policy and vulnerability reporting process.
-
- Special thanks to:
- - **Ryan Vonbrubeck** ([@dodge1218](https://github.com/dodge1218)) for responsible disclosure of command injection vulnerability
-
-Listed on [mcpservers.org](https://mcpservers.org)
- Built with the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
- Inspired by Norse mythology and Heimdall, the all-seeing guardian
---
## π¬ Contact & Support
**Sarvatarshan Sankar**
- GitHub: [@sarva-20](https://github.com/sarva-20)
- Repository: [heimdall-mcp](https://github.com/sarva-20/heimdall-mcp)
---
**π‘οΈ Heimdall is now watching over your system. βοΈ**
Made with β€οΈ by [Sarvatarshan Sankar](https://github.com/sarva-20)
**[π Visit Website](https://heimdall-mcp-v02.vercel.app)** β’ [β Star on GitHub](https://github.com/sarva-20/heimdall-mcp) β’ [Report Bug](https://github.com/sarva-20/heimdall-mcp/issues) β’ [Request Feature](https://github.com/sarva-20/heimdall-mcp/issues)