artsonia-mcp#

MCP server for Artsonia — natural-language access to student-art portfolios, comments, and fans.

• npm: npmjs.com/package/artsonia-mcp
• Source: github.com/chrischall/artsonia-mcp

Setup#

Option A — npx (recommended)#

Add to .mcp.json in your project or ~/.claude/mcp.json:

json

{
  "mcpServers": {
    "artsonia": {
      "command": "npx",
      "args": ["-y", "artsonia-mcp"],
      "env": {
        "ARTSONIA_USERNAME": "your-email@example.com",
        "ARTSONIA_PASSWORD": "your-password"
      }
    }
  }
}

Option B — from source#

bash

git clone https://github.com/chrischall/artsonia-mcp
cd artsonia-mcp
npm install && npm run build

Then add to .mcp.json:

json

{
  "mcpServers": {
    "artsonia": {
      "command": "node",
      "args": ["/path/to/artsonia-mcp/dist/index.js"],
      "env": {
        "ARTSONIA_USERNAME": "your-email@example.com",
        "ARTSONIA_PASSWORD": "your-password"
      }
    }
  }
}

Or use a .env file in the project directory with ARTSONIA_USERNAME=<value> and ARTSONIA_PASSWORD=<value>.

Authentication#

Username/password auth using your Artsonia parent/fan account credentials. The server logs in and maintains a session cookie.

Tools#

Core#

ToolDescriptionartsonia_healthcheckCheck connectivity and authentication statusartsonia_list_studentsList all students linked to the account

Portfolio & Artwork#

ToolDescriptionartsonia_get_activityGet recent activity feed for a studentartsonia_get_portfolioGet a student's art portfolio. Optional include_details: boolean (default false) fetches each artwork's full detail (title/project/grade/views/…) concurrently and merges it into the rows; omit it for the fast, lean tiles.artsonia_get_artworkGet details for a single artworkartsonia_download_artworkDownload a student's artwork images to a local folder. dest must be inside ARTSONIA_OUTPUT_DIR when set, else ~/Downloads or ~/Pictures ( $MCP_DATA_DIR/downloads when hosted); any other folder is refused before anything is fetched. Optional path_template: string (e.g. "{grade}/{project}" or "{school_year}") organizes downloads into subfolders under dest, composed with filename_template — same tokens ( {title} {project} {grade} {date} {school_year} {artwork_id}), segments slugified like filenames, empty tokens collapse, and paths stay deterministic so skip_existing re-runs remain idempotent. Optional embed_metadata: boolean (default false) embeds each image's title/project/grade and source date (its Last-Modified) into the JPEG's EXIF (ImageDescription, DateTimeOriginal) and IPTC (title, keywords, date) so the metadata survives renames/moves and is searchable in Spotlight/Apple Photos; the count is returned as embedded_count (best-effort — a failed embed writes the original bytes). Optional write_index: boolean (default false) writes an index.json manifest into the destination listing the downloaded items ( artwork_id, title, file — dest-relative, grade, project, date); the manifest path is returned as index_file. Optional write_metadata: boolean (default false) writes a per-artwork <image-name>.json sidecar next to each image with the artwork's comments and teacher feedback (plus title/project/grade); the count is returned as metadata_count. Optional include_private: boolean (default true) — set false to exclude private pieces ( private_excluded_count reports how many were dropped). The result carries totals ( total_bytes, downloaded_count/ skipped_count/ failed_count/ private_count), a per-file is_private flag, omitted_count/ omitted (only when an inline-delivery deployment dropped images over its 10 MiB per-result cap — those are fetched but NOT delivered, so they are not in downloaded), and — on unfiltered runs — a count_check against the student's artwork_count with a warning when the pull looks partial. Runs in one call — no confirmation step.

Social#

ToolDescriptionartsonia_list_commentsList comments on an artworkartsonia_get_fansGet the fan list for a studentartsonia_post_commentPost a comment on an artworkartsonia_invite_fanInvite someone to become a fan of a studentartsonia_set_notificationsUpdate notification preferences for a student

Confirming writes#

artsonia_post_comment and artsonia_invite_fan ask the user to confirm first. ( artsonia_set_notifications, artsonia_mark_feedback_read and artsonia_download_artwork run in one call with no confirmation step.) Where the client can show a confirmation prompt, it does (unless the server sets MCP_CONFIRM_ELICITATION=off). Otherwise the first call changes nothing and returns status: "confirmation-required" with a preview of exactly what would be sent and a confirmToken: show the preview to the user, and only after they approve in chat call the tool again with the same arguments plus confirmToken. A token works once ( TOKEN_REUSED), expires, and is refused as DRAFT_CHANGED (with a fresh preview and token) if the arguments or the data it acts on changed in between. MCP_CONFIRM_MODE ( ask-user default / auto / refuse) controls this fallback.

Environment Variables#

VariableRequiredDescriptionARTSONIA_USERNAMEYesYour Artsonia login email addressARTSONIA_PASSWORDYesYour Artsonia account passwordARTSONIA_TRANSPORTNoOverride transport: stdio (default), sse, or fetchproxy``ARTSONIA_WS_PORTNoWebSocket port when using sse transportARTSONIA_INLINE_DOWNLOADSNoSet to 1 on a hosted deployment to return artsonia_download_artwork images as inline base64 blocks instead of writing them to a disk the user can't reach. Leave unset for local installs.ARTSONIA_SESSION_CACHENoSet to false to disable the on-disk session cache and log in on every start. Defaults to enabled (direct transport only).MCP_CONFIRM_MODENoWhat a write does on a client that cannot show a confirmation prompt: ask-user (default — preview + token, user approves in chat), auto (the model may use the token after reviewing the preview), or refuse. An unrecognised value is treated as refuse.MCP_CONFIRM_ELICITATIONNooff never shows a confirmation prompt, so every client gets the MCP_CONFIRM_MODE token flow — for a client that claims to support prompts but never shows one (the write hangs — opencode 2.0.x). Defaults to on; any other value stays on, with a warning on stderr.MCP_CONFIRM_TTL_SECONDSNoHow long a confirmation token stays valid. Defaults to 600.MCP_CONFIRM_SECRETNoToken signing key; set it only if tokens must survive a server restart. Defaults to random per process.ARTSONIA_SESSION_FILENoOverride the session cache path. Defaults to $MCP_DATA_DIR/.artsonia-mcp/session-<user>.json — one file per user, so per-credential clients do not clobber each other.