# Macvis > MacVis β€” open-source local-first AI agent for macOS. Multi-provider (Claude, GPT, Gemini, Ollama). Full Mac access via MCP. BYOK, no backend, no telemetry. Download free. - **Type:** MCP server - **Install:** `agentstack add mcp-asim266-macvis` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [asim266](https://agentstack.voostack.com/s/asim266) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [asim266](https://github.com/asim266) - **Source:** https://github.com/asim266/macvis - **Website:** https://asim266.github.io/macvis/ ## Install ```sh agentstack add mcp-asim266-macvis ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # MacVis β€” open-source local-first AI agent for macOS **A free desktop AI assistant for Mac with full system access, multi-provider model routing (Claude / GPT / Gemini / Ollama), and Model Context Protocol (MCP) integrations.** 🌐 **Website:** [asim266.github.io/macvis](https://asim266.github.io/macvis/) Β· πŸ“¦ **Download:** [latest .dmg release](https://github.com/asim266/macvis/releases/latest) Bring-your-own-key. Multi-provider. No backend. No telemetry. Full Mac access. [](LICENSE) [](#) [](#) [](#multi-provider-with-fallback) > *Like Claude Desktop or ChatGPT for Mac β€” but you own the agent, your data, and the model choice.* ## Download **[⬇ Download the latest .dmg](https://github.com/asim266/macvis/releases/latest)** The app is not code-signed yet, so on first launch macOS will warn you. Right-click the app β†’ **Open** β†’ **Open Anyway**. (Or run `xattr -d com.apple.quarantine /Applications/MacVis.app` once.) Prefer to build from source? See [Quick Start](#quick-start) below. --- ## What is MacVis? MacVis is a native macOS desktop assistant that runs the same kind of agentic loop you get from Claude or ChatGPT β€” only it lives entirely on your machine. The agent has full access to **bash**, your **filesystem**, **web search**, and your **developer platforms** via MCP. Every chat, every project, every API key stays on your Mac. Built for developers who want a real agent to drive their environment, without sending their workspace to a third party. ## Highlights - 🧠 **Multi-provider with fallback** β€” pick a primary, secondary, and tertiary model. If the primary rate-limits or errors out, MacVis automatically falls back to the next. - πŸ”‘ **6 providers, BYOK** β€” Anthropic (Claude), OpenAI (GPT), OpenRouter (200+ models), Google Gemini, Groq (fast Llama/Mixtral), Ollama (local). - βœ… **Live key validation** β€” every key has a one-click *Test* button that hits the provider's `/models` endpoint and pulls in the actual model list you have access to. - πŸ’Ύ **Persistent memory** β€” every chat is saved to `~/.macvis/sessions/`. Reopen the app and your history is there. The agent remembers what it built in prior turns. - πŸ“ **Projects view** β€” every code project the agent creates goes to `~/.macvis/workspace/projects/` and shows up in a dedicated Projects page with one-click *Open in Browser / Editor / Finder* plus *Run* for HTML/Node/Next/Python projects. - πŸ”Œ **MCP-ready** β€” first-class config for GitHub, Supabase, Vercel, Railway, Slack, Cloudflare, Netlify, Stripe (Phase 4 wires up live connections). - πŸ“‘ **Telegram remote** β€” single-user-gated bot for full agent access from your phone (Phase 7). - 🚫 **No database, no telemetry** β€” everything is flat JSON in `~/.macvis/`. Inspect, back up, sync β€” you own it. - 🎨 **Distinctive UI** β€” refined dark theme with warm-red accent, Geist typography, OKLCH-based design tokens. Inspired by Linear and Raycast. ### Full agent harness - πŸ› οΈ **35+ native tools** β€” `read_file` / `write_file` / `edit_file` / `multi_edit`, `glob`, `grep`, `bash` (+ background shells via `bash_output` / `kill_shell`), `web_search`, `web_fetch`, `todo_write`, and a `task` tool that spawns autonomous **sub-agents**. - πŸ–₯️ **Computer use with vision** β€” `computer` takes screenshots and drives the mouse/keyboard (shell backend by default, optional nut-js); `applescript`, `clipboard`, `open`, `notify`, `system_control`, `spotlight`, and `ocr` (on-device macOS Vision). - πŸ“„ **Documents** β€” `document` extracts text from PDF/Word/Excel; `create_document` generates real `.docx` / `.xlsx` / `.pptx`; `rag` indexes folders for "chat with your files" (embeddings + keyword fallback). - πŸ§‘β€πŸ€β€πŸ§‘ **Multi-agent teams** β€” describe a goal and MacVis spins up a PM + worker agents that plan and execute until done, shown in a **3D scene**, with **human-in-the-loop** approvals. ### Always-on & safe - πŸŽ™οΈ **Voice in/out** β€” speak to MacVis (Whisper) and have replies read back (macOS `say` / ElevenLabs). - πŸ–ΌοΈ **Image & file attachments** β€” drop/paste images for vision, or drop any file to have the agent read it. - ⏰ **Scheduled tasks** β€” run prompts on a cadence; πŸ”— **webhook triggers** β€” fire runs from Shortcuts/curl/cron. - βŒ˜β‡§M **menu-bar quick-launch**, ⚑ **smart model routing** (cheap model for simple turns), and **prompt caching** + a live **token/cost meter**. - πŸ›‘οΈ **Safety** β€” HITL approval + diff review for edits, a filesystem **sandbox** (protects `~/.ssh`, Keychains, `/etc`), an append-only **audit log** with secret redaction, and per-tool enable/disable. - 🧩 **Skills & one-click Packs** β€” installable skill playbooks plus 14 domain Packs (Web, Crypto, Scripting, Automation, Lead Gen, Data/AI, DevOps, Mobile, Content, Research, Finance, Support, E-commerce, Designβ†’Code) that wire up the right skills + MCPs + keys in a click. ## Screenshots *The empty chat β€” bold logomark, quick-prompt chips, and the agent ready to act.* *Tool calls render inline as terminal-style cards. Here the agent builds a SaaS landing page end-to-end, writing the HTML/CSS/JS itself.* *Chat API Keys β€” Anthropic primary + Gemini secondary fallback chain. Click* ***Test*** *and MacVis pulls the real model list from each provider.* *MCP Integrations β€” Quick Connect cards for GitHub / Vercel / Railway / Supabase, plus a catalog of 18 more (Cloudflare, Postgres, Slack, Linear, Notion, Stripe, …) and a Custom MCP option for anything else.* ## Multi-provider with fallback MacVis routes every chat turn through a configurable **fallback chain** of up to 3 model providers: ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Primary β”‚ ─▢ β”‚ Secondary β”‚ ─▢ β”‚ Tertiary β”‚ β”‚ (try first) β”‚ β”‚ (on fail) β”‚ β”‚ (last resort)β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` Set them in **Settings β†’ Chat API Keys β†’ Fallback Chain**. Examples: | Use case | Chain | |---|---| | Highest quality with safety net | Anthropic Opus β†’ OpenAI GPT-5 β†’ OpenRouter Sonnet | | Cheap + cheerful | Groq Llama β†’ Gemini Flash β†’ OpenAI Mini | | Offline-friendly | Ollama β†’ Anthropic Haiku β†’ OpenRouter | **Supported providers:** | Provider | Models | Where to get a key | |---|---|---| | **Anthropic** | Claude 4.5 family (Opus, Sonnet, Haiku) | [console.anthropic.com](https://console.anthropic.com/) | | **OpenAI** | GPT-5, GPT-4o, o-series | [platform.openai.com](https://platform.openai.com/api-keys) | | **OpenRouter** | 200+ models, one key | [openrouter.ai/keys](https://openrouter.ai/keys) | | **Google Gemini** | Gemini 2.5 Pro / Flash | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | | **Groq** | Llama 3.3, Mixtral (very fast) | [console.groq.com](https://console.groq.com/keys) | | **Ollama** | Anything you've pulled locally | install [Ollama](https://ollama.com), no key required | ## Quick Start ### Prerequisites - macOS 13 or newer - [Node.js](https://nodejs.org) 20+ - [pnpm](https://pnpm.io/installation) ### Run from source ```bash git clone https://github.com/asim266/macvis.git cd macvis pnpm install pnpm dev ``` The window opens, you go to **Settings β†’ Chat API Keys**, paste at least one key (Anthropic recommended), click *Test*, pick a model, and you're live. ### Your first session 1. **Settings β†’ Chat API Keys** β†’ paste an API key β†’ click **Test** β†’ pick a model 2. *(Optional)* Add a second provider for the **Fallback Chain** so retries are automatic 3. Go to **Chat** and try one of: - *"Create a Next.js todo app called my-todo"* - *"Build a landing page for a SaaS"* - *"List my Downloads folder"* - *"What's the disk space on this machine?"* 4. Check the **Projects** tab β€” anything code-shaped that the agent creates lands here automatically ## Tech Stack | Layer | Choice | |---|---| | Runtime | Electron 41 | | Bundler | electron-vite 5 + Vite 8 | | UI | React 18 + TypeScript | | Styling | Tailwind v4 + OKLCH design tokens | | Typography | Geist Sans + Geist Mono | | State | Zustand | | Config store | `conf` β†’ `~/Library/Application Support/macvis/config.json` | | Model SDKs | `@anthropic-ai/sdk`, `openai`, `@google/generative-ai` | | Package manager | pnpm | ## Architecture ``` ~/.macvis/ ← user data (BYOK home) β”œβ”€β”€ sessions/ ← persisted chat history (JSON per session) β”‚ └── .json β”œβ”€β”€ workspace/projects/ ← code projects the agent creates β”‚ └── / └── skills/ ← installable skill packs (Phase 6) macvis/ ← this repo β”œβ”€β”€ electron/ ← Node.js main process β”‚ β”œβ”€β”€ core/ β”‚ β”‚ β”œβ”€β”€ agent/ β”‚ β”‚ β”‚ β”œβ”€β”€ providers/ ← Provider abstraction β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ AnthropicProvider.ts β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ OpenAIProvider.ts (OpenAI, OpenRouter, Groq, Ollama) β”‚ β”‚ β”‚ β”‚ └── GeminiProvider.ts β”‚ β”‚ β”‚ β”œβ”€β”€ AgentLoop.ts ← Streaming loop + fallback router β”‚ β”‚ β”‚ β”œβ”€β”€ ToolBuilder.ts β”‚ β”‚ β”‚ └── ProviderValidator.ts β”‚ β”‚ β”œβ”€β”€ tools/ ← bash, filesystem, web search β”‚ β”‚ β”œβ”€β”€ sessions/ ← persistent chat history β”‚ β”‚ β”œβ”€β”€ projects/ ← project scanner + runner β”‚ β”‚ β”œβ”€β”€ config/ ← conf wrapper β”‚ β”‚ β”œβ”€β”€ mcp/ ← MCP client manager (Phase 4) β”‚ β”‚ β”œβ”€β”€ skills/ ← skill loader (Phase 6) β”‚ β”‚ └── telegram/ ← Telegraf bot (Phase 7) β”‚ β”œβ”€β”€ ipc/ ← One IPC handler module per domain β”‚ β”œβ”€β”€ main.ts ← BrowserWindow + app boot β”‚ └── preload.ts ← contextBridge β†’ window.macvis.* └── src/ ← React renderer β”œβ”€β”€ pages/ ← Chat, Settings, Projects, MCPs β”œβ”€β”€ components/ ← layout, chat, settings, ui β”œβ”€β”€ stores/ ← Zustand state └── App.tsx ← root + routing ``` The main process owns all I/O, AI calls, and tool execution. The renderer is pure UI and talks to the main process exclusively over a typed IPC bridge (`window.macvis.*`). ## Roadmap | Phase | Status | |---|---| | 1. Electron shell + chat + Anthropic streaming | βœ… | | 2. Full settings with multi-provider BYOK + validation | βœ… | | 3. Tool system: bash, filesystem, web search, projects, memory | βœ… | | 3b. Multi-provider routing with fallback chain | βœ… | | 4. MCP manager β€” live MCP server connectivity | βœ… | | 5. Platform integrations: GitHub, Vercel, Supabase, Railway, Slack, Stripe, Notion, Linear, … | βœ… | | 7. Telegram remote control (single-user-gated bot) | βœ… | | 8a. DMG packaging (arm64 + x64) | βœ… | | 8c. Auto-updater (electron-updater) | βœ… | | 6. Skills loader + one-click Packs | βœ… | | 9. Tool-call approval mode + diff review (HITL) | βœ… | | 10. Full tool harness (read/write/edit/grep/glob, web_fetch, sub-agents) | βœ… | | 11. Computer use + vision, OCR, document read/create, RAG | βœ… | | 12. Multi-agent teams (3D) + HITL | βœ… | | 13. Voice in/out, attachments, scheduling, webhooks, menu-bar hotkey | βœ… | | 14. Prompt caching, cost meter, context compaction, model routing | βœ… | | 15. Sandbox + audit log + secret redaction + per-tool toggles | βœ… | | 8b. Code-signing + notarization | ⏳ [#2](https://github.com/asim266/macvis/issues/2) | **Effectively the whole roadmap has shipped.** Code-signing/notarization is the last item (the release CI workflow is written and ready β€” see `docs/SIGNING.md`). ## Privacy - All conversation data stays on your Mac (`~/.macvis/sessions/`). - API keys are stored locally in `~/Library/Application Support/macvis/config.json`. - Provider validation hits the providers directly from your machine; no proxy in between. - **No analytics, no telemetry, no remote logging.** Open the network tab β€” every call is direct to a provider you configured. ## FAQ **Is MacVis free?** Yes β€” MIT-licensed. You pay only the AI providers you choose. Or use Ollama (local Llama, Mistral, Qwen, etc.) for zero cost. **Is there a Claude Desktop alternative for Mac that supports MCP?** Yes β€” MacVis is exactly that. 19 built-in MCP integrations plus a custom server form. **Can I run an AI agent locally on my Mac without sending data to the cloud?** Yes β€” combine MacVis with [Ollama](https://ollama.com) for a fully local agent loop. No internet, no API keys. **Is MacVis open source?** Yes β€” full source at [github.com/asim266/macvis](https://github.com/asim266/macvis). PRs welcome. **What models does MacVis support?** Anthropic (Claude Opus / Sonnet / Haiku), OpenAI (GPT-4o, GPT-5, o-series), Google Gemini (2.5 Pro / Flash), OpenRouter (200+ models), Groq (Llama, Mixtral), Ollama (any local model). **Does MacVis send my data anywhere?** No backend, no telemetry. Every API call goes directly from your Mac to the provider you configured. Conversations are JSON files in `~/.macvis/sessions/` on your machine. **How is MacVis different from Cursor / Continue / Claude Code?** Those are agent surfaces embedded in your IDE. MacVis is a standalone desktop assistant β€” it can drive bash, Finder, Mail, deploy to Vercel, send Slack messages β€” not just edit code. **Is the DMG signed?** Not yet β€” code-signing tracked in [#2](https://github.com/asim266/macvis/issues/2). For now, right-click β†’ Open on first launch, or run `xattr -d com.apple.quarantine /Applications/MacVis.app`. ## Comparable projects - **[OpenClaw](https://github.com/openclaw/openclaw)** β€” similar idea, web-based UI - **Claude Desktop** β€” Anthropic's first-party Mac app (Claude only, no agent loop) - **Open WebUI** β€” local model interface (focused on Ollama) - **Cursor / Continue.dev** β€” agent in editor (different surface) MacVis is for the case where you want a **standalone desktop agent** with multi-provider routing, persistent memory, and full Mac access β€” not a chat sidecar to your editor. ## Contributing **MacVis is built in the open β€” contributors of every level are welcome.** You don't need to be a TypeScript/Electron expert to help. Here are the easiest ways to start: ### πŸ› Find and report bugs The agent has access to bash, files, MCP servers, and Telegram β€” there are many ways to break it. Try unusual inputs, edge cases, low-bandwidth scenarios. **Open an issue with a repro and screenshot** β€” that alone is a huge help. See [Finding bugs](CONTRIBUTING.md#finding-bugs) for ideas. ### ✨ Pick up an issue - **[Good first issues β†’](https://github.com/asim266/macvis/labels/good%20first%20issue)** β€” small, scoped, well-defined - **[Help wanted β†’](https://github.com/asim266/macvis/labels/help%20wanted)** β€” bigger items that need extra hands - **[All open issues β†’](https://github.com/asim266/macvis/issues)** β€” pick anything that looks fun ### πŸš€ Build something new - Add a new **MCP integration** β€” almost mechanical, 5 minutes per provider. See [CONTRIBUTING.md β†’ Adding a new MCP integration](CONTRIBUTING.md#adding-a-new-mcp-integration). - Add a new **chat provider** β€” the `ChatProvider` interface normalizes everything. - Build out a **roadmap phase** (skills loader, auto-updater, image gen, …). ### Dev commands ```bash pnpm install pnpm dev # Electron + Vite HMR pnpm typecheck # tsc --noEmit (run before pushing) pnpm build # produces dist/MacVis-{ver}-{arch}.dmg for both architectures ``` Full guide: **[CONTRIBUTING.md](CONTRIBUTING.md)** By contributing, you agree your contributions are licensed under [MIT](LICENSE). ## Disclaimer **MacVis is open-source software provided "AS IS", without warranty of any kind.** The agent has **full access to your Mac** β€” bash, filesystem, network, and any platforms you connect via MCP. You are giving an LLM the ability to run commands, modify files, deploy code, send messages, and spend money. **Treat it accordingly:** - **You are responsible** for every action MacVis takes on your machine. Review tool calls before they execute, especially `bash` and anything that touches money or production systems. - **The author(s) and contributors of MacVis are not liable** for any loss, damage, data corruption, unintended deploy … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [asim266](https://github.com/asim266) - **Source:** [asim266/macvis](https://github.com/asim266/macvis) - **License:** MIT - **Homepage:** https://asim266.github.io/macvis/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-asim266-macvis - Seller: https://agentstack.voostack.com/s/asim266 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.