🛡️ 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:

cd website npm install npm run dev

---

🚀 Quick Start

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

git clone https://github.com/sarva-20/heimdall-mcp.git cd heimdall-mcp bun install

Configure Claude Desktop

Find your paths:

which bun # Get Bun path pwd # Get Heimdall path

Edit config:

open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add:

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

• 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