Heimdall

sarva-2036

The all-seeing guardian for macOS: Battery, Clipboard, TTS, and File System control using Claude desktop

Install

Install and configure the MCP from https://github.com/sarva-20/heimdall-mcp.git now. Follow the repository's installation instructions, ask me for anything you can't complete yourself, and verify its tools load.

View source on GitHub

README

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

🔒 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

🛡️ Heimdall is now watching over your system. ⚔️

🌐 Visit Website • ⭐ Star on GitHub • Report Bug • Request Feature