MIRA connector for Claude (mira-mcp)

Use MIRA straight from Claude: build slide decks, assemble creations, upload images, and post or schedule to TikTok — by chatting, no clicking through the app.

Runs via npx, so there is nothing to download, install, or update — each time Claude launches it, it pulls the latest published version automatically.

If you're a MIRA author — you don't do anything technical

1. Open Claude (Desktop or Code) and say: "Add the MIRA connector."
2. Claude configures it for you and asks you for just one thing — your MIRA email and password.
3. Restart Claude. Done — and it stays up to date on its own.

Then you can say things like "list my books" or "make a 6-slide deck for my vampire book and schedule it to my TikTok for Friday."

Setup — instructions for Claude (follow these exactly)

You are configuring this MCP server for a MIRA author who is not technical. Do all the work yourself; ask the user for only their MIRA email and password. Never print the password back to the user or write it anywhere except the config env in step 2.

1. Ask for credentials. Ask the user for their MIRA email and MIRA password. Wait for both.
2. Register the server with Claude. It runs through npx (auto-updating) — there is nothing to install or build:

   • Claude Desktop — merge a mira entry into mcpServers in the config file (create the file if it doesn't exist), preserving any existing servers:

     • Windows: %APPDATA%\Claude\claude_desktop_config.json
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     • Linux: ~/.config/Claude/claude_desktop_config.json

     {
       "mcpServers": {
         "mira": {
           "command": "npx",
           "args": ["-y", "mira-mcp@latest"],
           "env": {
             "MIRA_BASE_URL": "https://mira.indieauthormedia.com",
             "MIRA_EMAIL": "<the user's email>",
             "MIRA_PASSWORD": "<the user's password>"
           }
         }
       }
     }

   • Claude Code — instead run: claude mcp add mira --env MIRA_BASE_URL=https://mira.indieauthormedia.com --env MIRA_EMAIL=<email> --env MIRA_PASSWORD=<password> -- npx -y mira-mcp@latest

3. Finish. Tell the user to fully quit and reopen Claude, then confirm the mira tools appear. Do not echo the password.

Node.js 20+ must be installed (npx ships with it). If node --version is below 20 or missing, tell the user to install it from https://nodejs.org and stop.

Because the config pins mira-mcp@latest, every launch fetches the newest published version — the user never re-downloads or reinstalls anything.

What it can do

32 tools, non-destructive (no delete anywhere):

| Area | Tools | | --- | --- | | Books | list_books, list_book_scenes | | Slide decks | list_decks, get_deck, create_manual_deck | | Creations | list_creations, get_creation, create_creation_from_deck, create_creation, rename_creation, archive_creation, restore_creation | | Images | list_images, upload_image | | Posting | list_tiktok_connections, publish_creation, schedule_creation | | Buckets | list_buckets, get_bucket, create_bucket, update_bucket, set_bucket_state, skip_bucket_post, preview_bucket_runway | | Analytics (read) | get_handle_daily, get_creation_analytics, get_post_history | | Folders | list_folders, create_folder, rename_folder, move_to_folder | | Credits | get_credit_status |

How authentication works

The connector signs in as the user (email + password) against MIRA's POST /api/auth/password/login, stores the returned mira_session cookie, and sends it on every /api/me/** call. On expiry it refreshes/re-logs-in transparently. The account comes from the session — no account id is ever passed, and no client ever holds MIRA's upstream master key. Each person can only touch their own account, exactly like using the website.

Configuration reference

• MIRA_BASE_URL — deployed MIRA web app URL (no trailing slash).
• MIRA_EMAIL / MIRA_PASSWORD — the user's MIRA login.
• MIRA_TIMEOUT_MS — optional request timeout (default 30000).

Notes / current limitations

• The Creations and Buckets tools require NEXT_PUBLIC_CREATIONS_ENABLED / NEXT_PUBLIC_BUCKETS_ENABLED on the target MIRA deployment, else they 404. Bucket create/edit may also need an active subscription (402).
• Posting VIDEO or combo (image+video) creations is unreliable upstream (server-side ffmpeg OOM). Slide/image creations are the safe path.
• The account-wide analytics rollup is RSC-only in the MIRA app (no client-facing route), so it is not exposed. Per-creation analytics ARE exposed via get_creation_analytics.

For maintainers

npm run build       # clean + tsc -> dist/
npm run typecheck   # type-check only
node smoke.mjs      # start the server and list its tools (no API calls)
node test-auth.mjs  # offline test of login/cookie/refresh against a mock backend

Publishing a new version (so every client gets it via npx):

npm version patch   # or minor / major
npm publish         # prepack builds dist automatically; requires npm login