macwhisper-mcp-server 1.0.0__tar.gz

macwhisper_mcp_server-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

macwhisper_mcp_server-1.0.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: macwhisper-mcp-server
+Version: 1.0.0
+Summary: Local MCP server exposing MacWhisper transcription to Claude Desktop.
+Author: Thomas
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/docdyhr/macwhisper-mcp-server
+Project-URL: Issues, https://github.com/docdyhr/macwhisper-mcp-server/issues
+Keywords: mcp,macwhisper,transcription,claude,llm
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp==3.2.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# macwhisper-mcp-server
+
+Local MCP server that connects [MacWhisper](https://goodsnooze.gumroad.com/l/macwhisper) to [Claude Desktop](https://claude.ai/download).
+
+**What it does:** Drop an audio file on your Desktop, then ask Claude to transcribe it, summarise it, or pull out action items — in one step. MacWhisper does the transcription on your Mac; Claude does the thinking. Nothing leaves your machine. No cloud APIs. No data ever leaves your Mac.
+
+```
+Audio file  →  MacWhisper CLI  →  MCP server  →  Claude Desktop
+```
+
+[![CI](https://github.com/docdyhr/macwhisper-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/docdyhr/macwhisper-mcp-server/actions/workflows/ci.yml)
+
+---
+
+![Claude Desktop transcribing an audio file](images/MacWhisper-MCP-server.png)
+
+---
+
+## Requirements
+
+- macOS (MacWhisper is macOS-only)
+- [MacWhisper](https://goodsnooze.gumroad.com/l/macwhisper) — installed, licensed, CLI enabled in Settings
+- Python 3.13.x via [pyenv](https://github.com/pyenv/pyenv)
+- [Claude Desktop](https://claude.ai/download)
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/docdyhr/macwhisper-mcp-server.git
+cd macwhisper-mcp-server
+
+pyenv install 3.13.13   # skip if already installed
+pyenv local 3.13.13
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Verify the MacWhisper CLI is reachable:
+
+```bash
+/Applications/MacWhisper.app/Contents/MacOS/mw --help
+```
+
+If you get "command not found": open MacWhisper → Settings → enable CLI.
+
+---
+
+## Configure Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` and add:
+
+```json
+{
+  "mcpServers": {
+    "macwhisper": {
+      "command": "/Users/<you>/macwhisper-mcp-server/.venv/bin/macwhisper-mcp",
+      "args": [],
+      "env": {
+        "MACWHISPER_ALLOWED_PATHS": "/Users/<you>/Desktop:/Users/<you>/Downloads"
+      }
+    }
+  }
+}
+```
+
+Replace `<you>` with your macOS username. Restart Claude Desktop.
+
+### Verify it works
+
+In Claude Desktop, ask:
+
+> Transcribe ~/Desktop/memo.m4a
+
+You should see a `transcribe_audio` tool call appear, followed by the transcript.
+
+---
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `transcribe_audio(path, model?)` | Transcribe an audio file and return the transcript as plain text |
+| `cancel_transcription()` | Cancel the currently running transcription |
+| `list_allowed_paths()` | Return the directories the server is allowed to read from |
+| `start_watch(folder)` | Watch a folder and auto-transcribe new audio files into `../done/` |
+| `stop_watch()` | Stop the active folder watcher |
+| `get_watch_results()` | Return completed watch-folder transcriptions and clear the queue |
+
+Supported audio formats: `.m4a` `.mp3` `.mp4` `.mov` `.wav` `.aiff` `.flac`
+
+---
+
+## Configuration
+
+All configuration is via environment variables. Pass them through the `env` dict in `claude_desktop_config.json` (for Claude Desktop) or set them in `.env` for local development.
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `MACWHISPER_ALLOWED_PATHS` | `~/Desktop` | Colon-separated list of directories the server may read from |
+| `MACWHISPER_CLI` | auto-detected | Path to the `mw` binary. Defaults to `/Applications/MacWhisper.app/Contents/MacOS/mw` if that file exists, otherwise `mw` on `PATH` |
+| `MACWHISPER_LOG_PATH` | `~/Library/Logs/macwhisper-mcp.log` | Log file path (never stdout — that's reserved for MCP) |
+
+**Local development:** copy `.env.example` to `.env` and adjust. With [direnv](https://direnv.net/), `.envrc` exports `.env` automatically. Without direnv: `source .env`.
+
+---
+
+## Development
+
+```bash
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Tests
+pytest -q
+
+# Lint + format
+ruff check .
+ruff format .
+
+# Pre-commit hooks (one-time setup)
+pip install pre-commit
+pre-commit install
+
+# Smoke-test against a real audio file (server must not be running in Claude Desktop)
+python scripts/smoke_test.py ~/Downloads/Test.m4a
+```
+
+### Logs
+
+```bash
+tail -f ~/Library/Logs/macwhisper-mcp.log
+```
+
+---
+
+## Security
+
+- All file paths are resolved (symlinks followed) and checked against the `MACWHISPER_ALLOWED_PATHS` allow-list before anything reaches the CLI.
+- `subprocess.run` is always called with an argv list — never `shell=True`.
+- No network calls. Ever.
+
+See [PRD §7](./PRD.md) for the full threat model.
+
+---
+
+## Known limitations
+
+- **Danish letter names:** Whisper may phonetically approximate letter names (e.g. "Æ, Ø, Å" → "E, Y, U") when they are spoken in isolation. Letters *inside words* transcribe correctly. This is a Whisper engine limitation, not a bug in this wrapper. See [PRD §12](./PRD.md).
+- **Cold-start latency:** First transcription after MacWhisper launches takes ~13s (model load). Subsequent calls are ~2s.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

macwhisper_mcp_server-1.0.0/README.md

@@ -0,0 +1,158 @@
+# macwhisper-mcp-server
+
+Local MCP server that connects [MacWhisper](https://goodsnooze.gumroad.com/l/macwhisper) to [Claude Desktop](https://claude.ai/download).
+
+**What it does:** Drop an audio file on your Desktop, then ask Claude to transcribe it, summarise it, or pull out action items — in one step. MacWhisper does the transcription on your Mac; Claude does the thinking. Nothing leaves your machine. No cloud APIs. No data ever leaves your Mac.
+
+```
+Audio file  →  MacWhisper CLI  →  MCP server  →  Claude Desktop
+```
+
+[![CI](https://github.com/docdyhr/macwhisper-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/docdyhr/macwhisper-mcp-server/actions/workflows/ci.yml)
+
+---
+
+![Claude Desktop transcribing an audio file](images/MacWhisper-MCP-server.png)
+
+---
+
+## Requirements
+
+- macOS (MacWhisper is macOS-only)
+- [MacWhisper](https://goodsnooze.gumroad.com/l/macwhisper) — installed, licensed, CLI enabled in Settings
+- Python 3.13.x via [pyenv](https://github.com/pyenv/pyenv)
+- [Claude Desktop](https://claude.ai/download)
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/docdyhr/macwhisper-mcp-server.git
+cd macwhisper-mcp-server
+
+pyenv install 3.13.13   # skip if already installed
+pyenv local 3.13.13
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Verify the MacWhisper CLI is reachable:
+
+```bash
+/Applications/MacWhisper.app/Contents/MacOS/mw --help
+```
+
+If you get "command not found": open MacWhisper → Settings → enable CLI.
+
+---
+
+## Configure Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` and add:
+
+```json
+{
+  "mcpServers": {
+    "macwhisper": {
+      "command": "/Users/<you>/macwhisper-mcp-server/.venv/bin/macwhisper-mcp",
+      "args": [],
+      "env": {
+        "MACWHISPER_ALLOWED_PATHS": "/Users/<you>/Desktop:/Users/<you>/Downloads"
+      }
+    }
+  }
+}
+```
+
+Replace `<you>` with your macOS username. Restart Claude Desktop.
+
+### Verify it works
+
+In Claude Desktop, ask:
+
+> Transcribe ~/Desktop/memo.m4a
+
+You should see a `transcribe_audio` tool call appear, followed by the transcript.
+
+---
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `transcribe_audio(path, model?)` | Transcribe an audio file and return the transcript as plain text |
+| `cancel_transcription()` | Cancel the currently running transcription |
+| `list_allowed_paths()` | Return the directories the server is allowed to read from |
+| `start_watch(folder)` | Watch a folder and auto-transcribe new audio files into `../done/` |
+| `stop_watch()` | Stop the active folder watcher |
+| `get_watch_results()` | Return completed watch-folder transcriptions and clear the queue |
+
+Supported audio formats: `.m4a` `.mp3` `.mp4` `.mov` `.wav` `.aiff` `.flac`
+
+---
+
+## Configuration
+
+All configuration is via environment variables. Pass them through the `env` dict in `claude_desktop_config.json` (for Claude Desktop) or set them in `.env` for local development.
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `MACWHISPER_ALLOWED_PATHS` | `~/Desktop` | Colon-separated list of directories the server may read from |
+| `MACWHISPER_CLI` | auto-detected | Path to the `mw` binary. Defaults to `/Applications/MacWhisper.app/Contents/MacOS/mw` if that file exists, otherwise `mw` on `PATH` |
+| `MACWHISPER_LOG_PATH` | `~/Library/Logs/macwhisper-mcp.log` | Log file path (never stdout — that's reserved for MCP) |
+
+**Local development:** copy `.env.example` to `.env` and adjust. With [direnv](https://direnv.net/), `.envrc` exports `.env` automatically. Without direnv: `source .env`.
+
+---
+
+## Development
+
+```bash
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Tests
+pytest -q
+
+# Lint + format
+ruff check .
+ruff format .
+
+# Pre-commit hooks (one-time setup)
+pip install pre-commit
+pre-commit install
+
+# Smoke-test against a real audio file (server must not be running in Claude Desktop)
+python scripts/smoke_test.py ~/Downloads/Test.m4a
+```
+
+### Logs
+
+```bash
+tail -f ~/Library/Logs/macwhisper-mcp.log
+```
+
+---
+
+## Security
+
+- All file paths are resolved (symlinks followed) and checked against the `MACWHISPER_ALLOWED_PATHS` allow-list before anything reaches the CLI.
+- `subprocess.run` is always called with an argv list — never `shell=True`.
+- No network calls. Ever.
+
+See [PRD §7](./PRD.md) for the full threat model.
+
+---
+
+## Known limitations
+
+- **Danish letter names:** Whisper may phonetically approximate letter names (e.g. "Æ, Ø, Å" → "E, Y, U") when they are spoken in isolation. Letters *inside words* transcribe correctly. This is a Whisper engine limitation, not a bug in this wrapper. See [PRD §12](./PRD.md).
+- **Cold-start latency:** First transcription after MacWhisper launches takes ~13s (model load). Subsequent calls are ~2s.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

macwhisper_mcp_server-1.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "macwhisper-mcp-server"
+version = "1.0.0"
+description = "Local MCP server exposing MacWhisper transcription to Claude Desktop."
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+license = "MIT"
+authors = [{ name = "Thomas" }]
+keywords = ["mcp", "macwhisper", "transcription", "claude", "llm"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: MacOS X",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "fastmcp==3.2.4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock>=3.12",
+    "ruff>=0.6",
+]
+
+[project.scripts]
+macwhisper-mcp = "macwhisper_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/docdyhr/macwhisper-mcp-server"
+Issues = "https://github.com/docdyhr/macwhisper-mcp-server/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = []
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-ra --strict-markers"

macwhisper_mcp_server-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

macwhisper_mcp_server-1.0.0/src/macwhisper_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""macwhisper-mcp-server — local MCP server exposing MacWhisper transcription."""
+
+__version__ = "1.0.0"

macwhisper_mcp_server-1.0.0/src/macwhisper_mcp/config.py

@@ -0,0 +1,61 @@
+"""Configuration loaded from environment variables."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_ALLOWED = str(Path.home() / "Desktop")
+DEFAULT_LOG_PATH = str(Path.home() / "Library" / "Logs" / "macwhisper-mcp.log")
+
+# MacWhisper ships its CLI binary inside the app bundle and does not put it on PATH
+# by default. Prefer the app-bundle path if present, fall back to `mw` on PATH.
+_BUNDLED_CLI = Path("/Applications/MacWhisper.app/Contents/MacOS/mw")
+DEFAULT_CLI = str(_BUNDLED_CLI) if _BUNDLED_CLI.exists() else "mw"
+
+# File extensions accepted by MacWhisper. Reject anything else before invoking the CLI.
+ALLOWED_EXTENSIONS: frozenset[str] = frozenset(
+    {".m4a", ".mp3", ".mp4", ".mov", ".wav", ".aiff", ".flac"}
+)
+
+
+@dataclass(frozen=True)
+class Config:
+    allowed_paths: tuple[Path, ...]
+    mw_cli: str = DEFAULT_CLI
+    log_path: Path = field(default_factory=lambda: Path(DEFAULT_LOG_PATH))
+
+    @classmethod
+    def from_env(cls) -> Config:
+        raw = os.environ.get("MACWHISPER_ALLOWED_PATHS", DEFAULT_ALLOWED)
+        allowed = tuple(Path(p).expanduser().resolve() for p in raw.split(":") if p.strip())
+        if not allowed:
+            raise ValueError("MACWHISPER_ALLOWED_PATHS must contain at least one directory.")
+
+        log_path_str = os.environ.get("MACWHISPER_LOG_PATH", DEFAULT_LOG_PATH)
+        log_path = Path(log_path_str).expanduser()
+        home = Path.home()
+        # resolve() without strict handles non-existent paths via lexical .. collapsing.
+        if home not in log_path.resolve().parents:
+            raise ValueError(
+                f"MACWHISPER_LOG_PATH must be inside your home directory ({home}). Got: {log_path}"
+            )
+
+        return cls(
+            allowed_paths=allowed,
+            mw_cli=os.environ.get("MACWHISPER_CLI", DEFAULT_CLI),
+            log_path=log_path,
+        )
+
+    def is_path_allowed(self, path: Path) -> bool:
+        """True if `path` resolves inside any of the allow-listed directories.
+
+        Uses `Path.resolve()` to follow symlinks before the prefix check, so a symlink
+        inside an allowed dir pointing outside is still rejected.
+        """
+        try:
+            resolved = path.resolve(strict=True)
+        except (FileNotFoundError, RuntimeError):
+            return False
+        return any(resolved == base or base in resolved.parents for base in self.allowed_paths)

macwhisper_mcp_server-1.0.0/src/macwhisper_mcp/server.py

@@ -0,0 +1,139 @@
+"""FastMCP server entry point.
+
+Run via `python -m macwhisper_mcp.server` or the `macwhisper-mcp` console script.
+Communicates over stdio — do NOT print to stdout anywhere. All logs go to a file.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import threading
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+from .config import Config
+from .transcribe import TranscribeError, transcribe
+from .watcher import FolderWatcher
+
+
+def _setup_logging(config: Config) -> None:
+    config.log_path.parent.mkdir(parents=True, exist_ok=True)
+    logging.basicConfig(
+        filename=str(config.log_path),
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+
+def build_server(config: Config | None = None) -> FastMCP:
+    config = config or Config.from_env()
+    _setup_logging(config)
+    log = logging.getLogger(__name__)
+    log.info("Starting macwhisper-mcp-server, allow-list=%s", config.allowed_paths)
+
+    mcp = FastMCP("macwhisper")
+
+    # --- concurrency + cancel state ---
+    _transcribe_lock = threading.Lock()
+    _current_proc: list[subprocess.Popen] = []  # at most one element
+
+    # --- watch-folder state ---
+    _watcher: list[FolderWatcher] = []  # at most one element
+
+    @mcp.tool()
+    def transcribe_audio(path: str, model: str | None = None) -> str:
+        """Transcribe a local audio file using MacWhisper and return the transcript.
+
+        Args:
+            path: Absolute path to an audio file inside the configured allow-list.
+                Supported formats: m4a, mp3, mp4, mov, wav, aiff, flac.
+            model: Optional model override in MacWhisper engine:model-id format,
+                e.g. "whisperkit:openai_whisper-large-v3-v20240930" or
+                "parakeet-pro:nvidia_parakeet-v3_494MB". Defaults to the model
+                currently selected in MacWhisper.
+
+        Returns:
+            The full transcript as plain text.
+        """
+        if not _transcribe_lock.acquire(blocking=False):
+            raise TranscribeError(
+                "Busy: another transcription is already running. Try again shortly."
+            )
+        _current_proc.clear()
+        try:
+            return transcribe(path, config, model=model, _proc_ref=_current_proc)
+        except TranscribeError:
+            log.warning("transcribe_audio failed: %s", path)
+            raise
+        finally:
+            _current_proc.clear()
+            _transcribe_lock.release()
+
+    @mcp.tool()
+    def cancel_transcription() -> str:
+        """Cancel the currently running transcription, if any."""
+        if not _current_proc:
+            return "No transcription is currently running."
+        _current_proc[0].kill()
+        log.info("Transcription cancelled by user")
+        return "Transcription cancelled."
+
+    @mcp.tool()
+    def list_allowed_paths() -> list[str]:
+        """Return the directories this server is allowed to read audio from."""
+        return [str(p) for p in config.allowed_paths]
+
+    @mcp.tool()
+    def start_watch(folder: str) -> str:
+        """Start watching a folder for new audio files to auto-transcribe.
+
+        New audio files dropped into ``folder`` are transcribed automatically
+        and moved to ``<folder>/../done/``. Call ``get_watch_results()`` to
+        retrieve completed transcriptions.
+
+        Args:
+            folder: Absolute or ``~``-prefixed path to the incoming directory.
+        """
+        if _watcher and _watcher[0].is_running:
+            return f"Already watching {_watcher[0].incoming}. Call stop_watch() first."
+        incoming = Path(folder).expanduser().resolve()
+        if not any(incoming == base or base in incoming.parents for base in config.allowed_paths):
+            raise TranscribeError("Access denied: folder is outside the configured allow-list.")
+        w = FolderWatcher(incoming, config)
+        w.start()
+        if _watcher:
+            _watcher[0] = w
+        else:
+            _watcher.append(w)
+        return f"Watching {w.incoming} — completed files moved to {w.done_dir}"
+
+    @mcp.tool()
+    def stop_watch() -> str:
+        """Stop the active folder watcher."""
+        if not _watcher or not _watcher[0].is_running:
+            return "No active watcher."
+        w = _watcher[0]
+        w.stop()
+        return f"Stopped watching {w.incoming}"
+
+    @mcp.tool()
+    def get_watch_results() -> list[dict]:
+        """Return completed watch-folder transcriptions and clear the queue.
+
+        Each entry contains: ``file``, ``transcript``, ``destination``, ``error``.
+        """
+        if not _watcher:
+            return []
+        return _watcher[0].drain_results()
+
+    return mcp
+
+
+def main() -> None:
+    build_server().run()
+
+
+if __name__ == "__main__":
+    main()