🛡️ Heimdall MCP Server ⚔️
🌐 Visit Official Website · Documentation · GitHub
"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 • 📖 Documentation • 🐛 Report Bug
✨ 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
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
🎬 Demo
🌐 Interactive Demo on Our Website - 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** - Complete setup instructions
- **Usage Guide** - Examples and commands
- **Troubleshooting** - Common issues and fixes
- **Contributing** - How to contribute
- **Changelog** - 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)
- **Claude Desktop** (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
---
## 📦 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
📜 License
MIT License - see LICENSE for details.
🙏 Acknowledgments
-
- ## 🔒 Security
-
- See SECURITY.md for our security policy and vulnerability reporting process.
-
- Special thanks to:
- - Ryan Vonbrubeck (@dodge1218) for responsible disclosure of command injection vulnerability
-
-Listed on mcpservers.org
- Built with the Model Context Protocol by Anthropic
- Inspired by Norse mythology and Heimdall, the all-seeing guardian
📬 Contact & Support
Sarvatarshan Sankar
- GitHub: @sarva-20
- Repository: heimdall-mcp
🛡️ Heimdall is now watching over your system. ⚔️
Made with ❤️ by Sarvatarshan Sankar
🌐 Visit Website • ⭐ Star on GitHub • Report Bug • Request Feature
