Documentation

Everything you need to install, configure, and use PRISM.

Installation

Option 1: npm (recommended)

# Install globally

npm install -g @synthcorp/prism

# Or run directly

npx @synthcorp/prism

Option 2: Binary download

Pre-built binaries for Windows, macOS, and Linux are available on the GitHub Releases page.

Option 3: Docker

docker pull ghcr.io/synthprism/prism:latest

Requirements: Node.js 22 or later. PRISM is built on Node 24 but supports 22+.

Authentication

Gmail (Google OAuth)

PRISM uses OAuth 2.0 with PKCE to authenticate with Gmail. Here's how to set it up:

1

Create a Google Cloud Project

Go to console.cloud.google.com and create a new project. Name it anything (e.g., "PRISM Email").
2

Enable the Gmail API

In your project, go to APIs & Services → Library. Search for "Gmail API" and click Enable.
3
Create OAuth Credentials

Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
- Application type: Desktop app
- Name: "PRISM" (or anything)
- Click Create
- Download the JSON file
4

Configure OAuth Consent Screen

Go to OAuth consent screen. Choose External user type. Fill in app name and your email. Add these scopes:

https://www.googleapis.com/auth/gmail.modify

https://www.googleapis.com/auth/gmail.compose

https://www.googleapis.com/auth/gmail.settings.basic

https://www.googleapis.com/auth/gmail.settings.sharing

Add your email as a test user under Test users.
5

Place credentials and authenticate

# Copy the downloaded JSON to PRISM's config dir

cp ~/Downloads/client_secret_*.json ~/.prism/credentials.json

# Run auth (opens browser)

prism auth

Your browser opens. Sign in with Google. Tokens are encrypted with AES-256-GCM and stored locally.

Security note: PRISM never sees your Google password. OAuth tokens are encrypted on your machine with a key derived from your hardware. Even if someone copies the token file, they can't decrypt it on a different machine.

Outlook (Microsoft Graph)

Outlook support uses Microsoft Graph API via MSAL. Documentation coming soon. For now, see the setup guide on GitHub.

MCP Configuration

Add PRISM to your AI client's MCP configuration.

Claude Code / Claude Desktop

Edit ~/.claude/.mcp.json:

{
  "mcpServers": {
    "prism": {
      "command": "prism"
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "prism": {
      "command": "prism"
    }
  }
}

Windsurf / Other MCP Clients

Any MCP-compatible client works. Just point the command to the prism binary. PRISM uses stdio transport by default.

Verify it works

# Check PRISM is running

prism status

# You should see:

PRISM v1.0.0 | Tier: community | Tools: 45 | Connected: Gmail

Tool Reference

PRISM exposes these tools to your AI client. Free-tier tools are marked with ●, Pro tools with ●.

Messages (16 tools)

● messages_list — Search/list messages

● messages_get — Get message by ID

● messages_send — Send email

● messages_trash — Move to trash

● messages_untrash — Restore from trash

● messages_modify — Add/remove labels

● messages_count — Count matching messages

● messages_get_headers — Headers only

● mailbox_search_count — Fast search count

● mailbox_stats — Inbox statistics

● messages_delete — Permanent delete (2-step)

● messages_get_raw — Raw RFC2822 source

● messages_import — Import message

● messages_insert — Insert message

● messages_batch_delete — Bulk delete

● messages_batch_modify — Bulk label changes

Threads (10 tools)

● threads_list — Search/list threads

● threads_get — Full thread with messages

● threads_get_messages — Message IDs in thread

● threads_count — Count threads

● threads_modify — Modify thread labels

● threads_trash — Trash thread

● threads_untrash — Restore thread

● threads_delete — Permanent delete

● threads_batch_modify — Bulk modify

Thread count shows 10; 9 listed here + messages_batch_trash which also operates on threads.

Drafts, Labels, Filters, Attachments, Profile

All draft, label, filter, and attachment tools are free-tier. See the full tool reference on GitHub for complete documentation with parameters and examples.

Pro-Only Categories

These categories require a Pro or Team license:

● Delegates (4 tools) — shared mailbox access

● Forwarding (4 tools) — forwarding rules

● Send-As (6 tools) — alias management

● Export (3 tools) — backup & forensics

● Settings writes (5 tools) — account configuration

● Push notifications (2 tools) — Pub/Sub

Troubleshooting

"insufficient authentication scopes"

Your OAuth token doesn't have the right permissions. Run prism auth again and make sure all 4 Gmail scopes are enabled in your Google Cloud Console.

"credentials.json not found"

Download your OAuth client credentials from Google Cloud Console and place the file at ~/.prism/credentials.json.

"token expired" or "invalid_grant"

Your refresh token expired (happens if your app is in "Testing" mode and hasn't been used in 7 days). Run prism auth to re-authenticate.

Rate limit errors (429)

PRISM has built-in rate limiting, but if you hit Google's quota, wait a few seconds and retry. The retry middleware handles this automatically for most cases.

Tool shows "requires Pro license"

That tool is in the Pro tier. Run prism status to see your current tier, or prism activate <key> to activate a license.

CLI Commands

prism # Start the MCP server (stdio)

prism auth # Authenticate with Gmail

prism status # Show connection, tier, tool count

prism activate <key> # Activate a license key

prism deactivate # Remove license key

prism --version # Show version

prism --help # Show all commands