OpenArchiver MCP Server

An MCP (Model Context Protocol) server for searching and administering an OpenArchiver instance.

Toolsets

Set OPENARCHIVER_TOOLSET to choose which tools MCP clients can discover. The default is core.

Core

Core is read-only and intended for everyday archive access:

• search_emails — search email text and structured fields.

• get_email — retrieve one archived email.

• get_archive_stats — return dashboard and per-source statistics together.

• get_archive_health — return global index health and optional per-source health.

• list_ingestion_sources — list accessible sources.

• list_archived_emails_for_source — browse a source with pagination.

Full

Full includes every core tool plus administrative tools:

• list_users, get_user, create_user, update_user, delete_user — user management.

• list_roles — discover IAM role IDs for user assignment.

• reindex_archive — reindex the entire archive or one source in missing or full mode.

• get_queues — inspect background queue counts.

In full mode, get_archive_health also requests the Super-Admin search-engine overview. Health sections are returned independently, so a permission failure in one section does not discard the others.

The API does not currently expose audit-log, retention-policy, retention-label, or legal-hold routes, so this MCP does not advertise nonfunctional tools for those features.

Related MCP server: outlook-evidence-mcp

Requirements

• Node.js 18 or newer

• A reachable OpenArchiver instance

• An OpenArchiver API key with permissions appropriate for the selected tools

Typical permissions include search:archive and read:archive for core access, read:dashboard and read:ingestion for statistics and health, manage:all for users, roles, queues, and index overview, manage:ingestion for a global reindex, and sync:ingestion for a source reindex.

Installation

npm install
npm run build
npm test

Run the published package directly with npx from GitHub Packages:

npx --yes --registry=https://npm.pkg.github.com --package=@imrasalghul/openarchiver-mcp@1.0.0 openarchiver-mcp

For GitHub Packages authentication, create a GitHub personal access token with read:packages (installation) or write:packages (publishing), then configure npm:

npm login --registry=https://npm.pkg.github.com --scope=@imrasalghul

Configuration

• OPENARCHIVER_API_KEY — required API key.

• OPENARCHIVER_API_URL — optional instance base URL; defaults to https://archiver.alghul.com.

• OPENARCHIVER_TOOLSET — core or full; defaults to core. Invalid values stop startup with an error.

• OPENARCHIVER_TIMEOUT_MS — positive request timeout in milliseconds; defaults to 30000.

Example MCP configuration:

{
  "mcpServers": {
    "openarchiver": {
      "command": "npx",
      "args": [
        "--yes",
        "--registry=https://npm.pkg.github.com",
        "--package=@imrasalghul/openarchiver-mcp@1.0.0",
        "openarchiver-mcp"
      ],
      "env": {
        "OPENARCHIVER_API_KEY": "your-api-key",
        "OPENARCHIVER_API_URL": "https://archiver.alghul.com",
        "OPENARCHIVER_TOOLSET": "core",
        "OPENARCHIVER_TIMEOUT_MS": "30000"
      }
    }
  }
}

Use "OPENARCHIVER_TOOLSET": "full" only for API keys intended to perform administrative operations.

The package is published to GitHub Packages, not npmjs.org.

Development

npm run build
npm test
npm run check

The tests start a local mock API and verify MCP discovery, tool annotations, input validation, reindex routing, partial health responses, and successful handling of 204 No Content deletions. They do not modify a live OpenArchiver instance.