@truss-dev/email-triage-mcp

Agentic email triage for Claude Code. Classify, extract tasks, auto-label, and manage your inbox — all from your AI agent.

This MCP server connects to Gmail and gives Claude Code (or any MCP-compatible agent) the ability to read, classify, search, and act on your email. No external AI APIs needed — classification runs locally using rule-based pattern matching. Your agent provides the intelligence; this server provides the data.

Quick Start

Run with npx (no install needed):

npx -y truss-email-triage-mcp

Claude Desktop / Claude Code

Add to your claude_desktop_config.json or .claude/settings.json:

{
  "mcpServers": {
    "email-triage": {
      "command": "npx",
      "args": ["-y", "truss-email-triage-mcp"]
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "email-triage": {
      "command": "npx",
      "args": ["-y", "truss-email-triage-mcp"]
    }
  }
}

Installation

npm install -g @truss-dev/email-triage-mcp

Claude Code Configuration

Add to your ~/.claude/settings.json or claude_desktop_config.json:

{
  "mcpServers": {
    "email-triage": {
      "command": "truss-email-triage",
      "env": {
        "GMAIL_CLIENT_ID": "your-client-id",
        "GMAIL_CLIENT_SECRET": "your-client-secret",
        "TRUSS_LICENSE_KEY": "truss_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Gmail Setup

1. Create OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable the Gmail API under APIs & Services > Library
4. Go to APIs & Services > Credentials > Create Credentials > OAuth 2.0 Client ID
5. Application type: Desktop app
6. Copy the Client ID and Client Secret

2. Set Environment Variables

export GMAIL_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GMAIL_CLIENT_SECRET="your-client-secret"

3. Authorize

Once the MCP server is running in Claude Code, use the authorize_gmail tool:

1. Call authorize_gmail with no arguments — it returns an authorization URL
2. Open that URL in your browser, sign in, and grant access
3. Copy the authorization code
4. Call authorize_gmail with code: "the-code-you-got"

Tokens are stored locally at ~/.truss/gmail-tokens.json and refresh automatically.

Tools Reference

Free Tier (10 classifications/day)

classify_email

Classify an email by intent.

Returns: Category (action_required, fyi, meeting_request, sales_pitch, support_ticket, newsletter, personal), confidence score, reasoning, and all category scores.

extract_action_items

Extract action items and deadlines from an email.

Returns: List of action items with description, deadline, priority, and assignee.

get_email_digest

Get a prioritized digest of all unread inbox emails.

Returns: Sorted list of unread emails with classification, priority, and action items.

search_emails

Search across emails using Gmail query syntax.

Returns: Matching emails with metadata and snippets.

Pro Tier ($25/mo — unlimited)

create_task

Create tasks in Linear, Jira, or Todoist from email content.

auto_label

Automatically label and archive emails based on classification.

Creates labels under the Triage/ prefix (e.g., Triage/Action Required, Triage/Newsletter).

batch_triage

Process all unread emails at once. Classify, label, extract tasks, and create external tasks in one operation.

smart_reply

Generate a draft reply based on email context.

email_analytics

Get usage patterns and sender analytics.

Returns: Category breakdown, top senders, response times, busiest hours, and insights.

follow_up_tracker

Track emails awaiting responses.

Utility Tools

check_auth_status

Check Gmail authentication and license status. No parameters.

authorize_gmail

Authorize Gmail access via OAuth2 flow.

Free vs Pro

Subscribe to Pro: https://buy.stripe.com/28E00igAv4605cWfXL7wA06

After subscribing, set the TRUSS_LICENSE_KEY environment variable.

Task Integration Setup

Linear

export LINEAR_API_KEY="lin_api_xxxxxxxx"

Get your API key at Linear Settings > API.

Todoist

export TODOIST_API_TOKEN="xxxxxxxx"

Get your token at Todoist Integrations > Developer.

Jira

export JIRA_DOMAIN="yourcompany"       # yourcompany.atlassian.net
export JIRA_EMAIL="you@company.com"
export JIRA_API_TOKEN="xxxxxxxx"

Get your API token at Atlassian API Tokens.

How Classification Works

The classifier uses rule-based pattern matching with no external AI API dependency. It analyzes:

• Headers: List-Unsubscribe (newsletter), In-Reply-To (thread context), Content-Type (calendar invites)
• Sender patterns: noreply@, support addresses, personal email domains
• Subject patterns: Action keywords, ticket numbers, forwarded messages, meeting language
• Body patterns: Action verbs, deadlines, meeting links, unsubscribe links, sales language

Each category has weighted rules. The email is scored against all categories and the highest-scoring category wins. Confidence reflects how strongly the patterns matched.

This design is intentional — your AI agent (Claude, etc.) provides the reasoning layer. The MCP server provides fast, deterministic, free email data access.

Data Storage

All data is stored locally on your machine:

No email content is sent to TRUSS servers. License validation is a simple key check.

Troubleshooting

"Gmail not authenticated"

Run check_auth_status to verify, then authorize_gmail to set up OAuth.

"Free tier daily limit reached"

Free tier allows 10 classifications per day (resets at midnight UTC). Upgrade to Pro for unlimited: Subscribe

"Gmail OAuth credentials not configured"

Set GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET environment variables. Create credentials at Google Cloud Console.

"This feature requires a TRUSS Pro license"

Pro tools (create_task, auto_label, batch_triage, smart_reply, email_analytics, follow_up_tracker) require a Pro subscription.

Token refresh errors

Delete ~/.truss/gmail-tokens.json and re-authorize with authorize_gmail.

SQLite errors

Delete ~/.truss/usage.db to reset the database. Usage counters will restart.

Development

git clone https://github.com/truss-dev/email-triage-mcp.git
cd email-triage-mcp
npm install
npm run build

# Run locally
npm run dev

# Run evals
npm run eval

License

MIT

A2A Discovery

This server publishes a Google A2A Protocol Agent Card, making it discoverable by any A2A-compatible agent framework (LangGraph, CrewAI, Google ADK, AutoGen, and others).

Agent Card: agent-card.json

The agent card describes this server's skills, capabilities, input/output modalities, and authentication requirements in a machine-readable format. A2A clients can use it to discover and invoke tools automatically without manual configuration.

# Fetch the agent card
curl https://raw.githubusercontent.com/claw-factory/email-triage-mcp/main/agent-card.json