Awaken MCP Server

Set AWAKEN_API_KEY and run the server over stdio:

export AWAKEN_API_KEY=your_awaken_api_key
bun link
bunx --no-install awaken-mcp-server

Passing the API key as the first CLI argument also works, but the environment variable is safer because it avoids exposing secrets in process listings.

For local development in this repo, bun start still works. The package now also exposes a CLI binary via bunx; after publishing or installing it as a dependency, bunx awaken-mcp-server is the expected entrypoint.

For Codex, configure the MCP server with the API key in env. A working example:

[mcp_servers.awaken]
command = "bunx"
args = ["awaken-mcp-server"]
env = { AWAKEN_API_KEY = "awk_client_..." }
startup_timeout_sec = 5.0

If env is omitted or the key is wrong, user-scoped queries like me { activeClient { id } } may return null and any tool that relies on the default active client will fail.

The server connects over stdio and talks to https://api.awaken.tax/graphql using:

Authorization: ApiKey <your_key>

Available tools:

• awaken_get_active_client
• awaken_list_labels
• awaken_get_transaction_type_options
• awaken_list_transactions
• awaken_label_transactions
• awaken_split_transaction
• awaken_split_wallet_transactions_and_label_fees

Notes:

• clientId is optional on every tool. If omitted, the server falls back to me.activeClient.id.
• Passing clientId explicitly is still safer when you already know the client from https://awaken.tax/clients/{id}.
• awaken_list_labels is the discovery tool for valid Awaken labels and categories.
• awaken_get_transaction_type_options shows transaction-specific category/label options and whether Awaken considers them applicable.
• walletAddress maps to Awaken's fromOrToAddress filter.
• amountGreaterThan and amountLessThan are local post-filters using priceCents when available.
• startDate and endDate must use YYYY-MM-DD.
• awaken_label_transactions requires label unless wipeLabel is true.
• For bulk fee categorization, start with dryRun: true and review the plan before applying mutations.
• awaken_split_wallet_transactions_and_label_fees now returns both results and failures so partial mutation failures are visible instead of failing as a single opaque error.