Skip to main content

aether-mcp CLI and MCP tools

Every aether-mcp command-line flag, environment variable, and subcommand, plus the three MCP tools that AI agents call. For the HTTP endpoints, see the HTTP API reference. For step-by-step setup, start with Install aether-mcp.

aether-mcp CLI flags and environment variables​

CLI flags override environment variables when both are set. Unknown flags and invalid values, such as a non-numeric --watch-ms, are rejected with a usage message and exit code 2. Output is plain text when it is piped, when NO_COLOR is set, or when TERM is dumb.

CLI flagEnvironment variableDefaultDescription
--vault <path>AETHER_VAULT_PATH.Root directory of the Obsidian Markdown vault
--db <path>None<vault>/.aether/aether.sqliteSQLite WAL index database path
--watch-ms <ms>None2000Vault polling interval in milliseconds (0 disables polling)
--http-addr <addr>AETHER_HTTP_ADDRDisabledBind SocketAddr for ControlPlaneServer (e.g. 127.0.0.1:14771)
--http-onlyNonefalseServes ControlPlaneServer without stdio MCP until Ctrl-C / SIGTERM (requires --http-addr)
--initNonefalseInstalls obsidian-aether-plugin, writes data.json, prints mcp.json, and exits (AETHER_PLUGIN_DIR overrides plugin source)
--require-authAETHER_REQUIRE_AUTH (1, true, yes)falseRequires Authorization: Bearer aek_<hex> and allows non-loopback HTTP binds
--bootstrap-admin-key <key>AETHER_BOOTSTRAP_ADMIN_KEYNoneEnsures an Admin key for AgentId "bootstrap-admin" exists in SQLite
--api-key <key>AETHER_API_KEYNoneBinds the stdio MCP session (or --init data.json / mcp.json) to a validated ScopedApiKey
--kv-endpoint <url>AETHER_KV_ENDPOINTNoneAttaches VllmLmCacheHttpAdapter targeting an http:// inference endpoint
--kv-model <id>AETHER_KV_MODELNoneSets VaultConfig::default_kv_model (ModelId) for recall kv_hint metadata

Subcommands and container image​

Command or imagePurpose
aether-mcp service install [--vault <path>] [--http-addr <addr>] [--watch-ms <ms>]Registers and starts an auto-starting user service (launchd on macOS, systemd --user on Linux, Task Scheduler on Windows; defaults --http-addr to 127.0.0.1:14771)
aether-mcp service statusPrints the status of the installed user service
aether-mcp service uninstallStops and removes the user service definition
aether-mcp setup [--vault <path>] [--yes] [--no-clients] [--no-service]Guided first-run setup: finds your Obsidian vaults (or lets you pick the current folder, browse for one, or type a path), installs the background service, offers a checklist of detected MCP clients to add aether-vault to, checks the result, and prints the next steps. --yes accepts the defaults and configures every detected client. Without a terminal and without --yes it exits with an explanation
aether-mcp uninstall [--vault <path>] [--purge-vault] [--yes]Stops and removes the background service, removes aether-vault from MCP client configs (other servers are kept), and prints how to remove the program. With --vault, also removes the vault's AMC plugin files; --purge-vault also deletes its .aether/ index and Aether/ folder. Notes are never deleted. Asks for confirmation unless --yes is given
aether-mcp doctor [--vault <path>]Checks the vault, the binary, and detected MCP client configs, with a fix hint beside each problem
aether-mcp completions <bash|zsh|fish|powershell|elvish>Prints a shell completion script to stdout
aether-mcp --help, aether-mcp --versionPrints usage or the version
aether-mcp doctor [--vault <path>]Checks the vault, the binary, and detected MCP client configs
aether-mcp completions <bash|zsh|fish|powershell|elvish>Prints a shell completion script to stdout
aether-mcp --help, aether-mcp --versionPrints usage or the version
npx @muninn-org/aether-mcpRuns the matching release binary through Node.js, downloading and verifying it on first use. See Install aether-mcp
ghcr.io/muninn-hq/aether-mcpMulti-arch (linux/amd64, linux/arm64) container image with ENTRYPOINT ["aether-mcp"] and /vault volume

MCP JSON-RPC 2.0 protocol and tools​

McpServer speaks newline-delimited JSON-RPC 2.0 (protocolVersion "2024-11-05") over stdio and POST /v1/mcp. Supported methods are initialize, ping, tools/list, and tools/call. Notifications (messages without id) produce no response line.

aether_recall​

Scoped sessions require the Reader role or higher.

ArgumentTypeRequiredDefaultDescription
querystringYesn/aNatural language or keyword query (may be empty if include_hot_profile is true)
scopestringNoAgent scopes or allFilter ScopeTag, intersected with caller scopes on scoped sessions
max_tokensintegerNo1500Strict positive token ceiling across static_prefix and dynamic_context
include_hot_profilebooleanNotrueIncludes deterministic [AETHER_HOT_PROFILE] prefix block
structuredbooleanNofalseWhen true, content[0].text contains JSON instead of formatted text
kv_modelstringNodefault_kv_modelTarget ModelId for attaching kv_hint block reuse metadata

structuredContent is always included on success with fields static_prefix, dynamic_context, prefix_hash, static_prefix_tokens, dynamic_tokens, tokens_used, and optional kv_hint.

aether_stage_memory​

Scoped sessions require the Contributor role or higher.

ArgumentTypeRequiredDefaultDescription
proposed_factstringYesn/aConcise non-empty atomic statement to stage in Aether/Inbox.md
suggested_tierstringNo"warm"One of "hot", "warm", or "cold"
scopestringNoagent.default_write_scope() or "global"Target ScopeTag (must be permitted for scoped callers)
target_notestringNoNoneSuggested vault note path or wikilink
supersedes_amu_idstringNoNoneOptional AmuId (amu_<32-hex> or UUID) of an active AMU to supersede on approval

Returns JSON { "candidate_id": "cand_<12-hex>", "inbox_path": "Aether/Inbox.md" }.

aether_inspect_source​

Scoped sessions require the Reader role or higher.

ArgumentTypeRequiredDefaultDescription
source_pointerstringYesn/aValidated SourcePointer (for example "Arch/DB.md#Schema" or "Aether/Compiled/Approved.md#cand_<hex>")

Reads live verbatim Markdown from disk while enforcing traversal guards, .aetherignore, aether_tier: private rejection, and scoped read authorization.