Skip to main content
Glama
inboxd
by 47star

inboxd

Warning: You use inboxd at your own risk. Users are responsible for evaluating the software, protecting their data and credentials, and handling any consequences of its operation.

Development status: inboxd is under active development. Features, configuration, APIs, and behavior may change without notice.

inboxd is a local, read-only archive for personal communications and work records on macOS. It collects available source data, stores it locally, indexes it for search, and makes it searchable by AI agents through MCP.

Highlights

  • Read-only collection. inboxd does not send messages or create, edit, move, or delete records in source services.

  • Durable local storage with RocksDB.

  • Full-text and substring search with Tantivy.

  • Incremental collection, checkpoints, reconciliation, retry handling, and local change history.

  • Attachment preservation and text extraction.

  • stdio MCP server backed by a local authenticated HTTP service.

  • Collector plugins discovered through the inboxd.collectors entry-point group.

  • macOS LaunchAgent and native EventKit, Messages, Mail, and Notes integration.

Source services remain authoritative. A complete local archive depends on source permissions, local macOS availability, network access, provider retention, and the collector's coverage rules.

Related MCP server: corpus-crm

Supported platform

  • Apple Silicon Mac

  • macOS 14 or later

  • Python 3.12 or 3.13

  • uv

  • Xcode Command Line Tools with xcrun, swiftc, and codesign

The native helper currently targets arm64-apple-macosx14.0. Linux, Windows, and Intel Mac installation are not supported.

Install

From the repository root:

uv sync --locked --python 3.12
uv run inboxd build-helper
mkdir -p "$HOME/.config/inboxd"

Configure the sources you want to use, then install the per-user LaunchAgent:

uv run inboxd install
uv run inboxd status

install registers and starts the LaunchAgent. It stops and replaces an existing inboxd LaunchAgent. build-helper is separate and is not run automatically by install.

The default paths are:

~/Applications/inboxd-source.app
~/Library/LaunchAgents/net.donghoon.inboxd.plist
~/Library/Application Support/inboxd/

The daemon and MCP server must use the same data directory and port.

Source plugins

The core package provides the standard collectors. Additional packages can register collectors with the inboxd.collectors entry-point group.

Each source is an independent entry point. The core registry does not contain a source list or source-specific defaults. Each plugin provides:

  • a source ID

  • a collector factory

  • a description shown by list_sources

  • default source configuration

  • optional content kinds and timestamp semantics

Installing or removing a plugin changes the available source set without changing core code. Set sources.<source_id>.enabled = false to disable one installed source while keeping its stored records searchable.

Plugin discovery is cached for the process lifetime. Restart the daemon after installing, removing, or repairing a plugin. Import failures, invalid definitions, duplicate source IDs, and collector initialization failures are reported per source; the remaining collectors and archive queries continue to run.

The archive persists source descriptions and content kinds. Removing a collector preserves queries and search-index rebuilding for its archived records. Set the source to enabled = false before uninstalling its package if its configuration remains in the file.

Built-in sources

Source

Data

Timestamp basis

messages

Locally available iMessage and SMS records

Message sent time

mail

Local Apple Mail EMLX files

Email sent time

slack

Authorized Slack conversations and threads

Message sent time

calendar

EventKit calendar occurrences

Occurrence start

notes

Notes available through the Notes application

Note creation time

reminders

EventKit reminders

Reminder creation time

google_calendar

Google Calendar events and recurring instances

Occurrence start

google_tasks

Google Tasks, including completed and hidden tasks

Task update time

redmine

Accessible Redmine issues and journals

Latest issue or journal time

Installed addons may add more rows to this list. Use list_sources to discover the active set.

Configuration

Configuration is loaded from ~/.config/inboxd/config.toml. Source-specific settings live under sources.<source_id>. A plugin owns its source defaults and may define additional keys.

Installed plugins validate configuration keys and value types before startup. Unknown keys, string booleans, non-finite intervals, and invalid ranges are rejected. Plugins can provide config_constraints for their defaults or a config_schema derived from inboxd.sources.configuration.SourceOptions. A disabled source whose package is absent retains its configuration for later reinstallation.

port = 48765
poll_seconds = 3
reconcile_seconds = 300
attachment_max_bytes = 104857600
diagnostic_retention_days = 30

[sources.messages]
enabled = true
poll_seconds = 3
reconcile_seconds = 300

[sources.slack]
enabled = true
reconcile_seconds = 3600
full_reconcile_seconds = 604800
event_poll_seconds = 0.2
connection_check_seconds = 10

[sources.google_calendar]
enabled = false
poll_seconds = 60
backfill_seconds = 1
start_year = 1970
future_years = 5

[sources.redmine]
enabled = false
url = "https://redmine.example.com/redmine"
poll_seconds = 60
reconcile_batch_size = 40

The complete built-in example is in config.example.toml. Do not overwrite an existing account configuration with the example file.

Set enabled = false under a source to stop its collector and attachment work. Existing records remain searchable.

General settings:

  • data_dir: archive, index, attachment, token, and log directory.

  • port: local HTTP port, default 48765.

  • poll_seconds: fallback collection interval.

  • reconcile_seconds: fallback reconciliation interval.

  • attachment_max_bytes: maximum preserved attachment size, default 100 MiB.

  • diagnostic_retention_days: number of daily diagnostic log files to retain.

Path settings are data_dir, messages_path, mail_path, apple_helper, and secrets_file. Use absolute paths. ~ and $HOME inside TOML values are not expanded.

INBOXD_DATA_DIR overrides the configured data_dir.

Configuration is read when the daemon starts. Apply changes by reinstalling the LaunchAgent:

uv run inboxd install

Secrets

Store credentials in ~/.config/inboxd/secrets.json with file mode 0600. Supported core keys include:

{
  "slack_app_token": "xapp-...",
  "slack_user_token": "xoxp-...",
  "redmine_api_key": "...",
  "redmine_feed_key": "..."
}

Environment variables are also supported for core credentials:

  • INBOXD_SLACK_APP_TOKEN

  • INBOXD_SLACK_USER_TOKEN

  • INBOXD_REDMINE_API_KEY

  • INBOXD_REDMINE_FEED_KEY

Additional collector packages may define their own credential keys and environment variables.

macOS permissions

The native helper needs:

  • Full Calendar access

  • Full Reminders access

  • Notes automation access

The LaunchAgent process also needs access to the Messages database and Apple Mail directories under macOS Privacy and Security settings. Permission granted to the native helper does not grant Python access to those directories.

Messages and Mail are local-source collectors. Records or attachments that macOS has not downloaded are not available to inboxd.

Google Calendar and Tasks

Enable the Calendar API and Tasks API in a Google Cloud project. Create a desktop OAuth client and run:

uv run inboxd google-auth --client-file /path/to/client_secret.json

Tokens are stored under data_dir/google/ with restrictive permissions. Use --no-browser to print the authorization URL instead of opening a browser.

Google collectors perform an initial backfill, persist page checkpoints, and then use incremental synchronization where supported. Google records are read from the local cache during search and message retrieval.

Slack

Slack requires both a Socket Mode app token and an authorized user token. A bot token cannot replace the user token when collecting user conversations.

Required secret keys:

{
  "slack_app_token": "xapp-...",
  "slack_user_token": "xoxp-..."
}

The required Slack scopes depend on the conversations and metadata to be collected. Typical scopes include channels:read, groups:read, im:read, mpim:read, the corresponding history scopes, users:read, users:read.email, team:read, files:read, and reactions:read.

Slack collection combines Socket Mode events with incremental reconciliation and periodic full reconciliation. A connected socket does not mean historical backfill is complete. Check backfilling, completed_channels, unavailable_channels, and last_success in source status.

Redmine

Configure the Redmine root URL under sources.redmine.url. Do not include /issues.

[sources.redmine]
enabled = true
url = "https://redmine.example.com/redmine"
poll_seconds = 60
reconcile_batch_size = 40

Redmine uses REST and Atom feeds. Initial collection stores checkpoints and issue metadata. Later collection uses feed signals followed by detail requests, with periodic reconciliation for changes that feeds do not expose.

MCP

inboxd exposes a stdio MCP server. The daemon must already be running.

For OpenCode:

opencode mcp add inboxd --global -- "$PWD/.venv/bin/inboxd-mcp"
opencode mcp list

For manual configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "inboxd": {
        "type": "local",
        "command": ["/absolute/path/inboxd/.venv/bin/inboxd-mcp"],
        "cwd": "/absolute/path/inboxd"
      }
    }
  }
}

The MCP server uses a local bearer token stored in data_dir/api-token. It does not start the daemon. The local HTTP API listens on 127.0.0.1 and is not an HTTP MCP endpoint.

MCP tools

Tool

Purpose

list_sources

Discover installed sources, coverage, and collector state

sync_status

Read daemon, collection, and indexing status

search_messages

Search titles, bodies, comments, and extracted attachment text

get_recent_records

Browse recent records without a search term

list_slack_conversations

Resolve Slack channels and direct messages

get_conversation

Browse one conversation oldest first

get_slack_thread

Read a Slack thread

get_message

Read bounded body segments and optional metadata

get_changes

Read durable ingestion changes

get_attachments

Read attachment preservation and extraction status

get_attachment_text

Read extracted attachment text

Recommended query flow:

  1. Call list_sources for the relevant source and inspect coverage.

  2. Call search_messages with order="newest" and a small limit when looking for the latest match.

  3. Follow read_request or next_request for the complete body.

  4. Use include_metadata=true only when source metadata or original markup is required.

Search terms must contain at least two characters. match="all" is the default. Use match="any" for alternate spellings or languages. before and after require timezone-aware ISO 8601 timestamps.

An empty result means no matching local record. Check source coverage, pending_index, backfill state, and permissions before treating it as absence from the original service.

Data and privacy

The archive is stored locally under data_dir:

rocksdb/             records, checkpoints, and change history
index/               Tantivy search indexes
attachments/         preserved attachment bytes
api-token            local HTTP authentication token
daemon.lock          single-daemon lock
logs/                diagnostics and process logs

Raw source payloads and metadata may contain sensitive information. Protect the data directory, secrets file, OAuth tokens, and generated logs. MCP responses are sent to the connected MCP client and may then be processed by an AI agent; local storage and downstream processing are separate concerns.

Stop the daemon before copying the data directory for backup. Restore the complete data directory and configuration while the daemon is stopped. Do not treat a live RocksDB directory copy as a consistent backup.

Operations

uv run inboxd status
uv run inboxd monitor --seconds 600
launchctl print "gui/$(id -u)/net.donghoon.inboxd"

Logs:

tail -n 100 "$HOME/Library/Application Support/inboxd/logs/diagnostics.jsonl"
tail -n 100 "$HOME/Library/Application Support/inboxd/logs/stderr.log"

The daemon uses a per-data-directory lock. Stop the LaunchAgent before running uv run inboxd serve manually:

launchctl bootout "gui/$(id -u)/net.donghoon.inboxd"
uv run inboxd serve

Reinstall the LaunchAgent after manual operation:

uv run inboxd install

Troubleshooting

MCP connection fails

  1. Run uv run inboxd status.

  2. Check launchctl print "gui/$(id -u)/net.donghoon.inboxd".

  3. Confirm .venv/bin/inboxd-mcp exists.

  4. Confirm the daemon and MCP process use the same data directory and port.

  5. Check diagnostics.jsonl, stderr.log, and api-token.

HTTP 401 usually means that the daemon and MCP server use different token files. HTTP 403 for a browser origin is expected for the local stdio-only access path.

Source access fails

Check the source status returned by list_sources. configuration_required indicates missing credentials or a missing native helper. source_unavailable indicates source access or permission failure. For Messages and Mail, verify macOS Full Disk Access for the actual LaunchAgent process.

Search results are missing

Check pending_index, source backfill state, time filters, and search mode. Use order="newest" for latest records. Resolve Slack names with list_slack_conversations before searching by conversation.

Development

make setup
make format
make check

make check runs Ruff, format checks, the layout checker, native checks, Swift formatting checks, and the Python test suite. The repository uses Python 3.12, Ruff 0.17.3, and the locked uv environment.

Build distribution artifacts:

uv build

Known limitations

  • Messages and Mail cover only data available locally on macOS.

  • Slack checkpoints are conversation-oriented; resuming in the middle of every page or thread is not guaranteed.

  • Slack offline changes and deletions are reconciled only within provider and collector limits.

  • Attachment extraction supports selected formats and bounded input sizes.

  • ready attachment state, successful collection, and completed search indexing are separate indicators.

  • Power loss, sleep, network loss, and provider errors are retried, but not every long-running recovery scenario is exhaustively verified.

  • Redmine stores fields and history exposed by the API and available to the configured account. Changes never retained by Redmine cannot be recovered.

License

inboxd is licensed under the GNU General Public License, version 3 or any later version. See LICENSE.

All trademarks referenced herein are the properties of their respective owners.

Available Tools

11 tools
get_attachmentsC

List attachment download and extraction states for a source record.

Inputs: message_id (required).

get_attachment_textC

Read extracted attachment text in bounded segments.

Inputs: id (required), length, offset.

get_changesB

Read durable ingestion changes, including edits/deletes, optionally scoped to one source.

Messages are bounded previews with read_request. Continue with the returned numeric cursor and the same source filter. These timestamps describe collection order, so historical backfill may appear among newly received changes. read_request retrieves the latest stored record, not a historical event version.

Inputs: limit, cursor, source.

get_conversationA

Browse conversation previews oldest first; follow next_request for subsequent pages.

Use get_recent_records with conversation_id for newest-first browsing. Deleted records are explicitly marked. Open read_request for a full body; no result proves only local absence.

Inputs: id (required), limit, cursor.

get_messageA

Read one local record with a bounded body segment, sender name and source metadata.

Use an ID returned by a query. offset and length count Unicode characters, not bytes. Follow next_request until next_offset is null for the remaining body. Raw transport payloads are omitted; they remain stored locally. Sender names reflect the latest collected profile. Work-item and source bodies are readable text including comments. Full metadata and original markup are opt-in via metadata_request or include_metadata=true, avoiding repeated large metadata on each body page. Offsets refer to the returned text representation.

Inputs: id (required), length, offset, include_metadata.

get_recent_recordsA

Browse content newest first without a search query, optionally scoped to one source.

Returns bounded previews and IDs for get_message/get_conversation. Excludes deleted records and Slack metadata entities. before/after are inclusive ISO 8601 timestamps with timezone. Calendar uses occurrence start, mail uses sent time, Notes/Reminders use creation time. Redmine uses issue update time and exposes work_item fields in previews. Future calendar entries are included unless before is supplied. For recently collected or modified data use get_changes instead. Continue with next_cursor and unchanged filters. For a specific channel or DM, pass conversation_id from list_slack_conversations.

Inputs: after, limit, before, cursor, +2 more.

get_slack_threadA

Read one Slack thread's locally archived root and replies in chronological order.

conversation_id comes from list_slack_conversations or a message. thread_id is the root's Slack timestamp: use a message's thread_id, or source_id for a root without thread_id. A reply's source_id is not its root timestamp. Returns bounded previews and sender names, with deleted items marked. Open read_request for full text. Continue with next_request. reported_reply_count is the last collected Slack value, not a guarantee of complete history.

Inputs: thread_id (required), conversation_id (required), limit, cursor.

list_slack_conversationsA

Find Slack channels, personal DMs and group DMs by channel name or participant name/email.

Returns conversation_id for scoped search, recent messages and thread lookup, plus known participants and per-conversation backfill state. kind selects public_channel, private_channel, dm or group_dm. user_id is an exact Slack user ID. account is a Slack workspace ID. Matching requires collected metadata; unknown membership may omit name/user matches. Continue with next_cursor and unchanged filters. Does not query or write to Slack remotely.

Inputs: kind, limit, query, cursor, +3 more.

list_sourcesA

Discover supported source IDs, collector health, coverage and latest content timestamps.

Stored record counts include metadata entities and deleted records; they are not active message counts. Inspect collector coverage before treating an empty result as source absence. Specify source when the task already identifies one, to avoid unrelated source metadata.

Inputs: source.

search_messagesA

Search communication, calendars, tasks, notes, reminders and installed source records.

Use order='newest', limit=1 for the latest matching message, code or email. The default order is relevance. before/after are inclusive ISO 8601 timestamps with timezone offsets. match='all' requires all terms; match='any' matches alternate spellings and languages. Each term needs 2+ characters; double quotes group a phrase. sender is an exact source ID, not a display name. conversation_id limits one conversation. Returns previews with read_request; follow next_request for another page. Profile/channel metadata is excluded. Check context for collection and indexing gaps. Searches titles, bodies, source comments and extracted attachments. Work-item HTML is rendered as text. matched_fields identifies where terms occur; preview_field identifies the excerpt source. Relevance scores title, body, comments and attachments separately.

Inputs: query (required), after, limit, match, +6 more.

sync_statusB

Return collector health, source coverage, counts and search-index backlog.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 11 tools

    Disambiguation3/5

    The core read path (search_messages, get_message, get_recent_records, get_changes) is well separated and descriptions even cross-reference each other to steer selection. However, sync_status and list_sources both return collector health/coverage counts, get_attachments and get_attachment_text are two ends of one workflow with the latter's description giving no hint of where its input comes from, and the Slack-specific get_slack_thread overlaps conceptually with the generic get_conversation.

    Naming Consistency4/5

    Nearly all tools follow a clear verb_noun snake_case pattern (search_messages, get_message, list_sources, get_slack_thread). The only deviation is sync_status, a noun phrase with no verb, plus get_changes which is mildly vague but consistent in style.

    Tool Count5/5

    11 tools is well within a healthy range for a multi-source archive covering mail, calendar, tasks, notes, reminders, Slack and work items. Each tool maps to a distinct retrieval need rather than padding the surface.

    Completeness4/5

    Read coverage is strong: search, single-record read, conversation browsing, change feed, source discovery, Slack channels/threads, and attachment text. Gaps are the near-absence of write/lifecycle operations (compose, mark read, update) and no attachment binary/download retrieval, though the descriptions imply a deliberately read-only local archive.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-compatible AI assistants to securely search multiple mailboxes, reconstruct email threads, and inspect attachments through read-only tools without altering mailbox state.
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables LLMs to query a personal message archive via MCP tools, including searching messages, resolving people, and retrieving conversation context.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to query your complete local conversation history and knowledge graph over MCP, including full-fidelity transcripts, search, and typed, dated entity relationships.
      AGPL 3.0