mac-whisper-tool

A CLI tool and MCP server for accessing meeting transcriptions from MacWhisper's database.

Overview

This tool provides both command-line interface and MCP (Model Context Protocol) server for MacWhisper's SQLite database. It enables users to list and export meeting transcriptions in various formats, and allows AI assistants to search and retrieve transcriptions via the MCP protocol.

Features

CLI Features

• List meetings with filtering by date range
• Search meetings by content keywords, title keywords, and date range
• Export transcriptions in multiple formats:
  • Markdown (standard or extended with metadata)
  • JSON (standard MacWhisper compatible or extended with metadata)
• Single session export or batch export
• Meeting start time estimation

MCP Server Features

• Search meetings by content keywords, title keywords, and date range
• Retrieve transcriptions as MCP resources or via tools (legacy mode)
• Extended Markdown format with timestamps and metadata
• Integration with AI assistants (e.g., Claude Desktop)
• Legacy mode support for older MCP clients that don't support Resources

Installation

Homebrew

The easiest way to install on macOS is via Homebrew:

brew install dayflower/tap/mac-whisper-tool

This will install the appropriate binary for your architecture (Intel or Apple Silicon).

Pre-built Binaries

Download the latest release for your macOS architecture from the Releases page:

• Intel Mac (x86_64): Download mac-whisper-tool_*_darwin_x86_64.tar.gz
• Apple Silicon (ARM64): Download mac-whisper-tool_*_darwin_arm64.tar.gz

Extract and install:

# Extract the archive
tar -xzf mac-whisper-tool_*_darwin_*.tar.gz

# Move to a directory in your PATH (optional)
sudo mv mac-whisper-tool /usr/local/bin/

From Source

go build -o mac-whisper-tool

The binary will be created in the current directory.

Usage

List Meetings

Display a list of meetings from the database:

# Show the most recent 20 meetings (default)
mac-whisper-tool list

# Show all meetings in JSON format
mac-whisper-tool list -n -1 -f json

# Filter by date range
mac-whisper-tool list -s 2025-12-01 -e 2025-12-31

# Estimate meeting start times (rounds to nearest 30 minutes)
mac-whisper-tool list --estimate-start

Options:

• -d, --db <path> - Database file path (default: ~/Library/Application Support/MacWhisper/Database/main.sqlite)
• -s, --start <datetime> - Filter by start date (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)
• -e, --end <datetime> - Filter by end date
• -n, --limit <n> - Maximum number of meetings (default: 20, negative for all)
• -f, --format <format> - Output format: table or json (default: table)
• --estimate-start - Estimate meeting start time from dateCreated and duration
• -v, --verbose - Enable verbose output to stderr

Search Meetings

Search for specific meetings by keywords, title, or date range:

# Search by content keyword
mac-whisper-tool search -k "budget"

# Search by multiple keywords (AND condition)
mac-whisper-tool search -k "zoom" -k "meeting"

# Search by title keywords
mac-whisper-tool search -t "standup" -t "team"

# Search with date range
mac-whisper-tool search -k "project" -s 2025-01-01 -e 2025-03-31

# Limit results
mac-whisper-tool search -k "meeting" -n 10

# JSON output
mac-whisper-tool search -k "Q4" -f json

# Estimate start times
mac-whisper-tool search -k "zoom" --estimate-start

Options:

• -k, --keywords <keyword> - Content keywords (repeatable, AND condition)
• -t, --title <keyword> - Title keywords (repeatable, AND condition)
• -s, --start <datetime> - Filter by start date (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)
• -e, --end <datetime> - Filter by end date
• -n, --limit <n> - Maximum number of results (default: 20, negative for all)
• -f, --format <format> - Output format: table or json (default: table)
• --estimate-start - Estimate meeting start time from dateCreated and duration
• -d, --db <path> - Database file path (inherited from global)
• -v, --verbose - Enable verbose output to stderr (inherited from global)

At least one search criterion (keywords, title, or date range) must be specified.

Export Transcriptions

Export a single meeting transcription:

# Export to stdout in Markdown format (default)
mac-whisper-tool export <session-id>

# Export to a specific file
mac-whisper-tool export -o output.md <session-id>

# Export to a directory with auto-generated filename
mac-whisper-tool export -c ./exports <session-id>

# Export in JSON format (MacWhisper compatible)
mac-whisper-tool export -f json <session-id>

# Export in extended Markdown format with metadata and timestamps
mac-whisper-tool export -x <session-id>

# Export in extended JSON format with metadata and timestamps
mac-whisper-tool export -f json -x <session-id>

# Estimate start time (internal calculation only, doesn't affect output)
mac-whisper-tool export --estimate-start <session-id>

# Estimate start time with extended content
mac-whisper-tool export --estimate-start -x <session-id>

Batch Export:

Export multiple meetings at once:

# Export the latest 10 meetings
mac-whisper-tool export -c ./exports -n 10

# Export meetings from a specific date range
mac-whisper-tool export -c ./exports -s 2025-12-01 -e 2025-12-31

# Export all meetings
mac-whisper-tool export -c ./exports -n -1

Options:

• -d, --db <path> - Database file path
• -f, --format <format> - Output format: markdown (or md), json (default: markdown)
• -o, --output <file> - Output file path (single session only)
• -c, --output-dir <dir> - Output directory (filename auto-generated)
• -x, --extend - Output extended content (timestamps, metadata)
• --estimate-start - Estimate meeting start time from dateCreated and duration
• -v, --verbose - Enable verbose output to stderr

Batch export options:

• -s, --start <datetime> - Filter by start date
• -e, --end <datetime> - Filter by end date
• -n, --limit <n> - Maximum number of meetings to export (negative for all)

Output Formats

Format vs Content

• Format (--format, -f): Specifies the output format

  • markdown (or md): Markdown format (default)
  • json: JSON format

• Content (--extend, -x): Specifies whether to include extended content

  • Default: Standard content (MacWhisper compatible)
  • -x: Extended content (includes timestamps and metadata)

• Start Time Estimation (--estimate-start): Estimates meeting start time

  • Internal calculation only, doesn't affect output format
  • When combined with -x, timestamps are based on estimated start time

Markdown

Standard format (default):

- **Speaker 1**: foo bar baz
- **Speaker 2**: hoge fuga

Extended format (-x):

# Zoom Meeting

- **Date Started**: 2025-07-23T10:00:00.000
- **Date Created**: 2025-07-23T11:59:59.000
- **Duration**: 38m 52s

- 2025-07-23T10:00:00.000 **Speaker 1**: foo bar baz
- 2025-07-23T10:20:30.400 **Speaker 2**: hoge fuga

JSON

Standard format (MacWhisper compatible):

[
  {
    "speaker": "Speaker 1",
    "text": "foo bar baz"
  },
  {
    "speaker": "Speaker 2",
    "text": "hoge fuga"
  }
]

Extended format (-f json -x):

{
  "title": "Zoom Meeting",
  "dateStarted": "2025-07-23T10:00:00.000",
  "dateCreated": "2025-07-23T11:59:59.000",
  "duration": 2332.4,
  "transcripts": [
    {
      "speaker": "Speaker 1",
      "text": "foo bar baz",
      "speakedAt": "2025-07-23T10:00:00.000"
    },
    {
      "speaker": "Speaker 2",
      "text": "hoge fuga",
      "speakedAt": "2025-07-23T10:20:30.400"
    }
  ]
}

Auto-generated Filenames

When using -c, --output-dir, filenames are automatically generated in the format:

{datetime} {title}.{ext}

Example: 2025-07-23T12:34:56.000 Zoom Meeting.md

Invalid filename characters are replaced with underscores.

Date/Time Handling

Input Formats

The tool accepts the following datetime formats:

• Date only: 2025-07-23 (treated as 2025-07-23T00:00:00.000)
• Date and time: 2025-07-23T11:22:33
• Date and time with milliseconds: 2025-07-23T11:22:33.000

Start Time Estimation

When using --estimate-start, the tool estimates the meeting start time by:

1. Subtracting the meeting duration from dateCreated
2. Rounding to the nearest 30 minutes

For example:

• Calculated time: 11:55 → Rounded to: 12:00
• Calculated time: 13:10 → Rounded to: 13:00

Database Location

The default database path is:

~/Library/Application Support/MacWhisper/Database/main.sqlite

Custom Database Path

You can specify a different database path using one of the following methods (in priority order):

1. Command-line flag (for one-time use, highest priority):

   mac-whisper-tool list --db /path/to/custom/main.sqlite
   

2. Environment variable (for session-wide use):

   export MAC_WHISPER_DB="/path/to/custom/main.sqlite"
   

3. Configuration file (for persistent use):

   Create a configuration file at one of these locations:

   • ~/.config/MacWhisperTool/config.json (recommended, XDG compliant)
   • ~/Library/Application Support/MacWhisperTool/config.json (macOS standard)

   Configuration file format:

   {
     "database": {
       "path": "/path/to/custom/main.sqlite"
     }
   }
   

   Example:

   # Create config directory
   mkdir -p ~/.config/MacWhisperTool
   
   # Create config file
   cat > ~/.config/MacWhisperTool/config.json <<EOF
   {
     "database": {
       "path": "~/custom/meeting.sqlite"
     }
   }
   EOF
   

Priority order:

1. --db flag (highest)
2. MAC_WHISPER_DB environment variable
3. ~/.config/MacWhisperTool/config.json
4. ~/Library/Application Support/MacWhisperTool/config.json
5. Default path (lowest)

MCP Server

Starting the Server

Start the MCP server to enable AI assistant integration:

# Start MCP server with default database
mac-whisper-tool mcp

# Use custom database path
mac-whisper-tool mcp --db /path/to/custom.sqlite

# Enable verbose logging to stderr
mac-whisper-tool mcp --verbose

# Enable legacy mode for older MCP clients
mac-whisper-tool mcp --legacy

Options:

• -d, --db <path> - Database file path (default: ~/Library/Application Support/MacWhisper/Database/main.sqlite)
• -v, --verbose - Enable verbose output to stderr
• --legacy - Enable legacy mode for MCP clients that don't support Resources
• --estimate-start - Estimate meeting start time by subtracting duration from creation time

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mac-whisper": {
      "command": "/usr/local/bin/mac-whisper-tool",
      "args": ["mcp"]
    }
  }
}

If you installed the tool in a different location, adjust the command path accordingly.

MCP Features

The MCP server provides:

1. search_meetings tool: Search meeting transcriptions

   • Search by content keywords (AND condition)
   • Search by title keywords (AND condition)
   • Filter by date range (after/before)
   • Limit results (default: 10, max: 100)
   • Returns JSON-formatted results with session metadata
   • In normal mode: Also returns resource links for each meeting
   • In legacy mode: Returns only JSON results (no resource links)

2. Resource access (normal mode only): Retrieve transcription content

   • URI scheme: macwhisper://localhost/session/{sessionID}
   • Returns extended Markdown format with timestamps and metadata
   • Use search_meetings tool to discover session IDs

3. get_meeting tool (legacy mode only): Retrieve transcription by session ID

   • Takes session ID as parameter
   • Returns extended Markdown format with timestamps and metadata
   • Alternative to Resources for older MCP clients

Legacy Mode

Legacy mode is designed for MCP clients that don't support the Resources feature. When running in legacy mode (--legacy):

• search_meetings returns JSON-formatted results without resource links
• get_meeting tool is available to retrieve transcriptions by session ID
• Resources are not registered

Normal mode (default):

mac-whisper-tool mcp
# - search_meetings returns JSON + resource links
# - Resources are available
# - get_meeting tool is NOT available

Legacy mode:

mac-whisper-tool mcp --legacy
# - search_meetings returns JSON only (no resource links)
# - Resources are NOT available
# - get_meeting tool is available

Error Handling

• Non-existent session ID: Error message to stderr, exit code 1
• Missing database file: Error message to stderr, exit code 1
• Missing output directory: Automatically created (exit code 1 on failure)
• Batch export without --output-dir: Error message to stderr, exit code 1

Examples

# List the latest 5 meetings with verbose output
mac-whisper-tool list -n 5 -v

# Export a specific meeting to a file with extended content
mac-whisper-tool export -x -o meeting.md abc123def456

# Batch export all meetings from December 2025 in extended JSON format
mac-whisper-tool export -c ./exports -f json -x -s 2025-12-01 -e 2025-12-31 -n -1

# Export using a custom database path with estimated start time
mac-whisper-tool export -d /path/to/custom.sqlite --estimate-start -x -c ./output sessionID

License

See LICENSE file for details.

Note

This tool is an experimental implementation. If you need modifications or additional features, please feel free to fork this repository and customize it for your own use.