🛡️ Heimdall MCP Server ⚔️

🌐 **Visit Official Website** | Documentation | GitHub

✨ Features

📁 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

• GitHub: @sarva-20
• Repository: heimdall-mcp