deClawed/README.md

deClawed

LLM-powered email triage and workflow automation via the Model Context Protocol

deClawed is an MCP server that connects your Gmail inbox to any LLM-capable client (such as Claude Desktop). Agents have access to tools to classify incoming emails, automate routine actions (delete, archive, summarize). The framwork integrates with Google Mail, Sheets and Calendar to keep your high-volume email workflow organized and actionable.

---

Getting Started

Requirements

Dependency	Version
Node.js	16+
npm	8+
Google Cloud Project	With Gmail API enabled
MCP Client	Claude Desktop (or any MCP-compatible client)

Installation

git clone https://git.sjdev.online/kjannette/deClawed-Assity-Kitty
cd deClawed-Assity-Kitty
npm install
npm run build

Google Cloud Setup

1. Create a project at Google Cloud Console
2. Enable the Gmail API (and optionally Sheets API and Calendar API)
3. Configure OAuth consent screen (External, add your email as a test user)
4. Create OAuth credentials (Desktop app) and download credentials.json
5. Place credentials.json in the accountsAndCredentials/ directory

Account Configuration

Create accountsAndCredentials/accounts.json:

{
  "work": {
    "label": "you@example.com",
    "tokenFile": "token.json",
    "spreadsheetId": "YOUR_GOOGLE_SHEET_ID",
    "calendarId": "primary"
  }
}

Authorize Gmail Access

npm run auth              # Authorize default account
npm run auth -- secondary # Authorize additional accounts

Follow the browser prompts to complete OAuth. Tokens are saved locally and auto-refresh.

Connect to Claude Desktop

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "assistant": {
      "command": "/path/to/node",
      "args": ["/path/to/deClawed-Assity-Kitty/build/index.js"]
    }
  }
}

Restart Claude Desktop. The server appears under Connectors.

---

Usage

Basic Workflow

In Claude Desktop, invoke the email review workflow:

Review my inbox

The server fetches unread emails, classifies them using your configured prompts, and executes the appropriate actions.

Classification Categories

Category	Description	Default Action
A	Acknowledgements, auto-replies	Delete
B	Advancement (interview requests, next steps)	Log + Calendar event
C	Rejections	Delete
D	Other/uncategorized	Log for review

Customizing Prompts

Edit the plain-text files in src/prompts/ to adjust classification rules and actions:

• classify-emails.txt — Defines category criteria
• take-action-on-emails.txt — Specifies actions per category

Changes take effect immediately without rebuilding.

---

MCP Tools Reference

Tool	Description
fetch_new_emails	Fetch unread emails with classification instructions appended
delete_emails	Move specified message IDs to trash
star_emails	Star messages and mark as read
append_to_summary	Log email metadata to local JSON (auto-purges after 30 days)
log_recruiter_contact	Append or update a row in Google Sheets
create_calendar_event	Create a Google Calendar event (skips past dates)

Example: Fetch Emails

fetch_new_emails(account: "work", maxResults: 50)

Example: Create Calendar Event

create_calendar_event(
  account: "work",
  title: "[Interview] Acme Corp - Senior Engineer",
  startDateTime: "2026-09-01T14:00:00-04:00",
  durationMinutes: 60,
  location: "https://zoom.us/j/123456789"
)

---

CLI Commands

Command	Purpose
npm run build	Compile TypeScript to build/
npm run auth	Authorize the default account
npm run auth -- <name>	Authorize a named account
npm test	Run test suite
npm run test:watch	Run tests in watch mode

---

Project Structure

deClawed-Assity-Kitty/
├── src/
│   ├── index.ts                 # Entry point
│   ├── McpServer.ts             # MCP server instance
│   ├── auth.ts                  # OAuth setup script
│   ├── loaders/                 # Config and prompt loaders
│   ├── prompts/                 # Classification and action prompts
│   └── tools/                   # MCP tool implementations
├── accountsAndCredentials/      # OAuth credentials and tokens (gitignored)
├── mailSummaries/               # Local email logs (gitignored)
├── test/                        # Unit and integration tests
└── build/                       # Compiled output

---

Security

• All credentials and tokens are stored locally and excluded from version control
• OAuth tokens auto-refresh; re-authorization is only needed if revoked
• The server runs locally via stdio—no network exposure

---

License

ISC