gmailql 1.2.0

GmailQL

Email operations via GraphQL -- CLI tool, MCP server, and API for Gmail and IMAP/SMTP providers.

Install

# Zero-install via .NET 10 dnx
dnx gmailql

# Or install as a global tool
dotnet tool install -g gmailql

Quick Start

# Log in to Gmail
gmailql login

# List inbox messages
gmailql messages list

# Read a message
gmailql messages read <id>

# Send a message
gmailql messages send --to alice@example.com --subject "Hello" --body "Hi there"

# Search messages
gmailql messages list --query "from:bob subject:meeting"

# Raw GraphQL query
gmailql query '{ messages(filter: { isUnread: true }) { items { subject from { email } } } }'

MCP Server

GmailQL includes an MCP server for AI agent integration with 3 tools: gmailql_query, gmailql_mutate, gmailql_schema.

Auto-Install

# Interactive setup — detects Claude Code, VS Code, Cursor, Windsurf
gmailql install-mcp

# Install to user config for all detected agents
gmailql install-mcp --user --all

# Install to project config for a specific agent
gmailql install-mcp --project --agent claude-code

Manual Configuration

Claude Code (~/.claude.json) — Windows:

{
  "mcpServers": {
    "gmailql": {
      "command": "cmd",
      "args": ["/c", "dnx", "gmailql", "--", "--mcp"]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "gmailql": {
      "command": "dnx",
      "args": ["gmailql", "--", "--mcp"]
    }
  }
}

Note: On Windows, dnx, npx, and uvx are .cmd scripts and need cmd /c.

HTTP GraphQL Server

cd src/GmailQL.Server
dotnet run
# GraphQL playground at http://localhost:5280/graphql

IMAP/SMTP Support

# Log in to any IMAP provider
gmailql login --provider imap --alias work

Features

• 32 CLI commands covering messages, drafts, labels, contacts, filters, attachments, setup
• GraphQL API with 10 queries, 18 mutations, and subscriptions for new mail
• MCP server with 3 coarse tools for minimal AI context usage
• install-mcp / uninstall-mcp auto-setup for Claude Code, VS Code, Cursor, Windsurf
• Multi-account with named accounts, switching, and per-query account selection via GraphQL
• Cross-platform credential storage — Windows Credential Manager, macOS Keychain, Linux libsecret, encrypted file fallback
• Gmail API optimizations — batch requests and exponential backoff on rate limits
• IMAP server-side search and proper attachment handling
• IMAP OAuth2 support (Microsoft 365 via XOAUTH2 SASL)
• OAuth token auto-refresh in long-running MCP sessions
• Interactive prompts when arguments are missing
• Output formats — --json, --output-format graphql, table, plain text
• GraphQL subscriptions for real-time new mail (polling + IMAP IDLE)
• Layered skill docs for AI agent context efficiency

Development

dotnet build gmailql.slnx
dotnet test gmailql.slnx
dotnet pack src/GmailQL.Tool/GmailQL.Tool.csproj -c Release

License

MIT