Purpose
Askew-mcp is Askew's local connector, a stdio-type MCP server used to let any AI agent (Claude Code, Claude Desktop, Cursor, Codex, or another MCP client) run Shortcuts on your iPhone, iPad, or Mac, send you notifications, and read back what the phone returns. The iPhone can stay locked while Shortcuts run.
Main capabilities
- Let MCP clients run installed Shortcuts on the device.
- Send lock-screen notifications to the phone and receive events and data sent back by the device.
- End-to-end encrypted transmission via a relay: task inputs, results, notification bodies, inbox entries, and variables use HPKE (X25519 + HKDF-SHA256 + ChaCha20-Poly1305) encryption; shared variables use a ChaCha20-Poly1305 box derived from the account key, with the variable name as AAD. The relay stores only encrypted envelopes and metadata (such as routing names, timestamps, and status).
- The 0.2 series supports explicit device selection, as well as specifying a local Mac target for execution.
- Provides local search and building of recipes, signing, and optional upload.
How to use
1. Get a connector key
In the Askew app on iPhone: Settings → Register device → allow notifications → New connector. Copy the key (akc_…); this key is shown only once.
2. Add the connector to the agent
Supports Claude Desktop / Cursor / any MCP client (claude_desktop_config.json, .cursor/mcp.json, etc.), and also supports Codex CLI (~/.codex/config.toml).
The first authenticated tool call creates ~/.askew/connector.key (X25519 private key, permissions 0600), registers the public key with the relay, and prints a six-word fingerprint to stderr (for example cider grove desert fever city burger). Check in the app's connector screen whether the six words match, then click "확인함 / Verified". This check rules out the risk of the relay having been replaced. Until it is completed, the app will show the connector as unverified, and the agent will be prompted to ask you.
3. Install the dispatcher on your phone
In the app's "Shortcuts (단축어)" tab, install the Askew dispatcher (Share Sheet → Shortcuts → Add), open it, and turn on the Automation toggle at the top. With the phone unlocked, run a test push from Settings → Checkup and tap Always Allow. Just one toggle, one allow. Then add recipes in the same way (Calendar, Reminders, Notes, etc.) to make requests to the agent, for example:
"Add dentist Thursday 3pm to my phone calendar."
Choosing a device or the local Mac
Call askew_list_routes and choose an enabled targets entry. Omitting target uses the route's default device; there is no broadcast. Target assignment is managed by the phone. To run an installed shortcut on the local Mac, use the corresponding route's actual input contract. The connector ID must match what askew_list_routes prints; that process cannot execute on another Mac. Both the target and the route must be enabled. Local execution requires macOS, an authenticated relay connection for reading assignments and emergency-stop snapshots, and executionMode: "auto". A stopped account or a server missing the stop-state field will prevent local execution. Stop is checked before dispatch and cannot undo the effects of a shortcut that is already running.
Local askew_run resolves the exact shortcut name to a unique installed identifier, runs it once, and returns the result directly to the MCP client. Inputs and outputs stay on the local Mac; no server task, usage billing, server run history, or last-success update is created. wait applies only to device tasks: Mac execution waits up to 60 seconds and returns a local_… task ID. askew_get_run reads that ID from the connector's local log (no long polling). Timeouts/failures may come with partial effects and are never retried automatically. Mac sleep may prevent execution.
Confirm-mode routes require a manual flow that the local executor does not implementprocess, and therefore will be rejected before running. For automatic Mac runs, a stable idempotency key (idempotencyKey, 1–200 characters) must be provided. The connector saves a persistent reservation before dispatch. Repeating the same request returns the saved result; changes to the input, routing, or shortcut name produce a conflict. If the process is interrupted or the failure is uncertain, it remains unknown, and the key will not be used to rerun. Requests without a key are independent runs. Do not delete/change the key and then blindly retry an uncertain attempt; check its effects first.
Local history is stored under local-runs/ next to ASKEW_KEY_PATH (usually ~/.askew/local-runs), separated by connector identity and public key. Records, results, and request summaries are encrypted to the connector key; raw input is not retained. Files are visible only to the local operating system user. Records are retained until manually deleted: deleting the log loses retry protection, and losing the private key loses access to old results. Keep the same key and log across restarts. Local history is provided by run ID and is not synced to the phone or relay.
Recipe upload and review
Local search/build does not require a connector key or relay connection. askew_recipe_build requires macOS for signing. Its default verify: true imports and runs the new shortcut on this Mac and may cause any effects produced by its actions; choose it only when those effects are authorized. verify: false only signs without importing or running. When signing, the workflow is sent to Apple (Apple documentation). A successful run does not prove correctness or safety.
sendToPhone: true connects to the relay only after a successful build. This uploads the signed file and the plaintext workflow, which may contain literal personal data or secrets. This path is outside the encrypted task/result/inbox channel. Do not embed sensitive values in shared recipes. Local execution output is returned to the MCP client, but is never uploaded as recipe metadata. Older clients that send verifiedRun text must be upgraded.
The relay checks the basic file structure and provides static hints from separately submitted workflows. It does not verify the archive signature, nor does it establish that the hints describe the file. Every agent recipe is always in an unverified state. In Askew › My Stuff, confirm that you will inspect the actual actions, permissions, and targets before adding it to Shortcuts. Downloading the file does not mean installation has been confirmed.
Inbox entries are always returned marked as data sent by the user's phone, not as instructions.
ConnectionAt times the server also sends MCP instructions: how runs flow through the scheduler, setup order, the symptom → cause comparison table (expired vs unknown vs failed), and how to combine recipes.
Requires Node 22 or newer.
Applicable scenarios and limitations
- Supports iPhone relay and local macOS targets; iPad background behavior still needs real-device verification; Android is not supported.
- The Askew app is currently in the waitlist stage (https://askew.my）。
- The connector is the only part of Askew that holds your key, and therefore also the part you can read.
- Source code:https://github.com/Dominic-DK/askew-mcp（欢迎提交 issue and pull request).
The above features, platforms, and limitations all come from the project description; other information is not yet available.
