inboxd
Collects local Apple Mail, Notes, Calendar, and Reminders data through native macOS integrations and archives it for search.
Collects Google Calendar events and recurring instances, with initial backfill and incremental synchronization.
Collects Google Tasks, including completed and hidden tasks, for local search.
Collects locally available iMessage and SMS records from the Mac and archives them for search.
Collects accessible Redmine issues and journals using REST and Atom feeds, with checkpoints and reconciliation.
Collects authorized Slack conversations and threads, including incremental reconciliation and historical backfill.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@inboxd search my messages and email for the flight confirmation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.collectorsentry-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
uvXcode Command Line Tools with
xcrun,swiftc, andcodesign
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 statusinstall 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_sourcesdefault 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 |
| Locally available iMessage and SMS records | Message sent time |
| Local Apple Mail EMLX files | Email sent time |
| Authorized Slack conversations and threads | Message sent time |
| EventKit calendar occurrences | Occurrence start |
| Notes available through the Notes application | Note creation time |
| EventKit reminders | Reminder creation time |
| Google Calendar events and recurring instances | Occurrence start |
| Google Tasks, including completed and hidden tasks | Task update time |
| 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 = 40The 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, default48765.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 installSecrets
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_TOKENINBOXD_SLACK_USER_TOKENINBOXD_REDMINE_API_KEYINBOXD_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.jsonTokens 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 = 40Redmine 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 listFor 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 |
| Discover installed sources, coverage, and collector state |
| Read daemon, collection, and indexing status |
| Search titles, bodies, comments, and extracted attachment text |
| Browse recent records without a search term |
| Resolve Slack channels and direct messages |
| Browse one conversation oldest first |
| Read a Slack thread |
| Read bounded body segments and optional metadata |
| Read durable ingestion changes |
| Read attachment preservation and extraction status |
| Read extracted attachment text |
Recommended query flow:
Call
list_sourcesfor the relevant source and inspect coverage.Call
search_messageswithorder="newest"and a small limit when looking for the latest match.Follow
read_requestornext_requestfor the complete body.Use
include_metadata=trueonly 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 logsRaw 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 serveReinstall the LaunchAgent after manual operation:
uv run inboxd installTroubleshooting
MCP connection fails
Run
uv run inboxd status.Check
launchctl print "gui/$(id -u)/net.donghoon.inboxd".Confirm
.venv/bin/inboxd-mcpexists.Confirm the daemon and MCP process use the same data directory and port.
Check
diagnostics.jsonl,stderr.log, andapi-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 checkmake 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 buildKnown 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.
readyattachment 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 toolsget_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
Scored across 11 tools
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.
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.
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.
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
Free, source-checked directory of AI agent tools, MCP servers and skills, with read-only search.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Read-only search over 2,065+ AI agent tools and 276 MCP servers. Free, no sign-up needed.
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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
- FlicenseNot gradedqualityCmaintenanceEnables LLMs to query a personal message archive via MCP tools, including searching messages, resolving people, and retrieving conversation context.-
- AlicenseNot gradedqualityBmaintenanceEnables searching imported AI conversations locally across different providers from an MCP client, with read-only access to the archive.43 PyPI1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables 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