Skype Archive CLI

Overview

Skype Archive CLI imports one uncompressed Skype export TAR into a local SQLite index, then provides fast local message, conversation, participant, and attachment browsing. The source archive is never modified and the application performs no network requests.

Related MCP server: openmessage

Privacy

All processing is local. The index and extracted-attachment cache under ~/.skype-archive-cli are unencrypted plaintext local data and can contain message text, names, identifiers, archive metadata, and attachment content. Protect them with the same care as the original export. The application uses private POSIX permissions where supported, but disk encryption and account security remain your responsibility. It performs no telemetry, update checks, or runtime network requests.

Prerequisites

• Node.js 24

• One uncompressed Skype export TAR

• A platform supported by better-sqlite3

Install

npm install -g skype-archive-cli --ignore-scripts=false

Quick Start

npm install -g skype-archive-cli --ignore-scripts=false
skype-archive import ~/Downloads/8_example_export.tar
skype-archive status
skype-archive messages "project update, deadline" --conv "=Synthetic Chat"
skype-archive convs Synthetic

CLI

Command reference

Global options

messages options

Context options require a non-empty search query.

attachment options

Human output is terminal-sanitized. Import progress and diagnostics use stderr. Interactive terminals receive one live progress line across scanning, message parsing, search indexing, finalization, and completion. Redirected stderr receives newline-delimited phase changes plus at most one ordinary update every five seconds. Progress contains only validated-offset archive percentage during scanning/message parsing and aggregate counts; --json stdout remains exactly one JSON document.

Message search treats spaces as OR and comma-separated groups as AND: hello world, deadline means (hello OR world) AND deadline. Filters include --conv, --participant, --from, --to, mutually exclusive --incoming/--outgoing, --type, and --has-attachment. -A, -B, and -C add 0 through 100 context messages around non-empty searches; -C supplies both sides unless -A or -B overrides that side.

Conversation selectors use an ID for an exact ID match, =Synthetic Chat for a case-insensitive exact display-name match, or plain Synthetic for a literal partial match. Exact names that identify multiple conversations report ambiguity instead of guessing.

Default attachment extraction uses the private managed cache and can reuse a validated cached file. --output accepts a new file path or an existing directory; destinations are created exclusively, so existing files and symlinks are never overwritten or followed.

JSON examples

With no active index, skype-archive status --json returns:

{"indexed":false,"compatible":false,"sourceState":"missing"}

A message search without context returns the exact top-level envelope below. Message objects contain the normalized list fields shown here:

{"messages":[{"rowId":42,"id":"synthetic-message-id","conversationId":"19:synthetic-thread","conversationName":"Synthetic Chat","senderId":"8:synthetic","senderName":"Synthetic User","timestamp":"2026-07-11T10:00:00.000Z","direction":"incoming","messageType":"Text","body":"Project update","attachmentCount":0,"isMatch":true}],"total":1,"conversationName":"Synthetic Chat"}

Context mode changes only the command envelope to grouped timelines:

{"groups":[{"conversationId":"19:synthetic-thread","messages":[{"rowId":42,"id":"synthetic-message-id","conversationId":"19:synthetic-thread","conversationName":"Synthetic Chat","senderId":"8:synthetic","senderName":"Synthetic User","timestamp":"2026-07-11T10:00:00.000Z","direction":"incoming","messageType":"Text","body":"Project update","attachmentCount":0,"isMatch":true}]}],"total":1,"conversationName":"Synthetic Chat"}

Inventory and extraction commands use command-specific envelopes. Each line below is a separate JSON document:

{"conversations":[]}
{"participants":[]}
{"attachments":[]}
{"attachment":{"path":"/tmp/synthetic-report.pdf","cached":false}}

Version 0.1 intentionally does not provide dedicated calls, unread state, or unanswered state. It supports one active archive only: there is no multi-archive merge or import through MCP.

See docs/MANUAL.md for the exact behavior and managed paths.

MCP

Import the export with the CLI before browsing it through MCP. The server still starts without an index so a client can list tools and call get_archive_status.

Run the published stdio executable without a global install:

npx -y --ignore-scripts=false -p skype-archive-cli skype-archive-mcp

Claude Desktop, Cursor, Codex, and other clients that accept stdio MCP JSON can use this configuration:

{
  "mcpServers": {
    "skype-archive": {
      "command": "npx",
      "args": ["-y", "--ignore-scripts=false", "-p", "skype-archive-cli", "skype-archive-mcp"]
    }
  }
}

The server registers exactly seven tools:

The six query tools advertise read-only, non-destructive, idempotent, closed-world annotations. extract_attachment differs only by advertising readOnlyHint: false; it has no destination argument and can write only below ~/.skype-archive-cli/attachments.

MCP list limits default to 20 and accept 1 through 200. Context values accept 0 through 100. Bodies in get_messages results are limited to 8,000 Unicode code points and include bodyTruncated: true when shortened; use get_message_by_id for the full body and raw content. For example, an MCP client can call get_messages with invented arguments { "query": "synthetic deadline", "context": 2, "limit": 10 }, then call get_message_by_id with the returned invented ID.

MCP does not expose import, arbitrary extraction destinations, dedicated calls, unread state, or unanswered state.

If status reports indexed: true and compatible: false, the index schema does not match this release. Re-import the export with the CLI before browsing it; MCP never imports archives.

The TAR reader accepts conventional zero-block trailers and producer-compatible clean EOF exactly after a complete 512-byte-aligned entry. It still rejects partial headers, truncated entry data, invalid sizes and checksums, unsafe paths, links, and special entries.

Testing

npm install --ignore-scripts=false
npm test
npm run lint
npm run pack:check

Private-safe manual checks are documented in test/AI_MANUAL_TESTING.md.

Releases

Maintainers publish a stable GitHub Release whose tag exactly matches v<package version>. A token-free verification job repeats the Node 24 install, lint, test, and package checks; a separate minimal OIDC job then publishes a missing version to npm. Existing npm versions are skipped safely, and prereleases are never published to the stable npm channel.

License

AGPL-3.0-only. See LICENSE.