convez.ai
MCP ServerProdutividadeAvançado
assistance-micro-design

Zileo MCP para Thunderbird

assistance-micro-design/zileo-mcp-thunderbird

56 ferramentas de IA para automação completa do Thunderbird

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que integra o Mozilla Thunderbird com assistentes de IA, expondo 56 ferramentas para gerenciar emails, contatos, calendário e tarefas. Funciona via WebExtension bridge, permitindo que Claude e outros agentes automatizem operações em Thunderbird com segurança através de Model Context Protocol.

Instalação

$npx convez-ai assistance-micro-design/zileo-mcp-thunderbird

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 2 meses
Versão
v1.5.1
Issues abertas
7
Contribuidores
2

Casos de uso

  • Automação de fluxo de trabalho de email com assistentes de IA
  • Gerenciamento em massa de contatos e calendários via commands naturais
  • Integração de Thunderbird com workflows de produtividade assistida por IA

Veredito

Ferramenta robusta e bem arquitetada para integração de Thunderbird com assistentes de IA via MCP. Requer cuidado com operações destrutivas (emails, contatos, eventos) e deve ser testada em perfil isolado antes de produção; recomenda-se backup preventivo. Status beta com API experimental para calendário.

README

A tradução para o português deste README ainda está na fila.

Zileo MCP — Thunderbird

Version License Status MCP Tools

Model Context Protocol (MCP) server for Thunderbird email client integration. This project enables AI assistants to interact with Thunderbird through a standardized protocol.

Developed by Assistance Micro Design

Built with Claude Code by Anthropic

Beta Warning

RiskDescription
Data LossThis tool can perform destructive operations (delete, move, modify) on emails, contacts, calendar events, and tasks. These actions cannot be undone.
AI AutonomyWhen used with AI assistants, the AI may execute actions based on its interpretation of your requests. Always verify destructive operations before confirming.
Breaking ChangesThe MCP protocol and this implementation may change without notice during the beta phase.
No WarrantyThis software is provided "AS IS" without warranty of any kind. See the LICENSE for details.

Recommendation: Back up your Thunderbird profile before first use. Test in a separate Thunderbird profile before connecting to production data. The Docker deployment is the recommended setup (process isolation, reproducible builds).

By using this software, you accept full responsibility for any data loss or unintended modifications.

Features

  • Email Management: Search, read, move, copy, delete, and archive emails (10 tools)
  • Email Composition: Create, reply, forward, save drafts/templates, and send (8 tools)
  • Folder Operations: Create, rename, move, delete folders and mark as read (7 tools)
  • Contact Access: Full CRUD operations on contacts and address books (9 tools)
  • Calendar Events: Create, update, move, delete events with recurrence support (9 tools) *
  • Task Management: Create, update, complete, and delete tasks (6 tools) *
  • Tag Management: Create, update, delete email tags with colors (4 tools)
  • Account Management: List accounts and identities (3 tools)
  • Resource Access: 6 static + 2 parameterized MCP resources

* Experimental features using webext-experiments calendar API

Total: 56 MCP Tools

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT MCP                               │
│        (Claude Desktop, Zileo Chat, MCP client)                 │
└─────────────────────┬───────────────────────────────────────────┘
                      │ JSON-RPC 2.0 (stdio)
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                    SERVEUR MCP                                  │
│                  (Node.js/TypeScript)                           │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐               │
│  │   Tools     │ │  Resources  │ │  WebSocket  │               │
│  │  Handler    │ │   Handler   │ │   Bridge    │               │
│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘               │
│         └────────────────┼───────────────┘                      │
│                          ▼                                      │
│              ┌───────────────────────┐                          │
│              │  WebSocket Client     │                          │
│              │  (ws://localhost:9876)│                          │
│              └───────────┬───────────┘                          │
└──────────────────────────┼──────────────────────────────────────┘
                           │ WebSocket
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                 EXTENSION THUNDERBIRD                           │
│                    (MailExtension V3)                           │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Background Script                      │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │   │
│  │  │ Messages │ │ Folders  │ │ Contacts │ │ Calendar │   │   │
│  │  │   API    │ │   API    │ │   API    │ │   API*   │   │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘   │   │
│  └─────────────────────────────────────────────────────────┘   │
│  * API Expérimentale (webext-experiments)                       │
└─────────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                      THUNDERBIRD                                │
│           (Emails, Contacts, Calendriers, Tâches)               │
└─────────────────────────────────────────────────────────────────┘

This is a monorepo containing two main components:

  • server/: Node.js MCP server that communicates with Thunderbird via WebSocket
  • extension/: Thunderbird WebExtension (Manifest V3) that provides native client access

Installation

Prerequisites

  • Node.js 20.x or higher (or Docker)
  • Thunderbird 128.x or higher
  • npm package manager

Option 1: Docker Setup (Recommended)

The Docker deployment provides process isolation and a multi-client architecture where the container runs a standalone WebSocket bridge, and MCP clients connect via docker exec.

  1. Clone and build:
git clone https://github.com/assistance-micro-design/zileo-mcp-thunderbird.git
cd zileo-mcp-thunderbird
docker compose build
  1. Start the bridge server:
cp .env.example .env   # optional — every variable has a safe default
docker compose up -d
  1. Install the Thunderbird extension:

    • Download the latest zileo-mcp-thunderbird-x.y.z.xpi from GitHub Releases, or build it from the sources with npm run package:extension (output in releases/)
    • Open Thunderbird
    • Go to Tools > Add-ons and Themes
    • Click the gear icon > Install Add-on From File
    • Select the downloaded .xpi file
  2. Verify the bridge is running:

curl http://localhost:9876/health
# Initially: {"status":"ok","thunderbird":false,"mcpClients":0}
# After extension connects: {"status":"ok","thunderbird":true,"mcpClients":0}

Architecture:

┌─────────────────────────────────────────────────────┐
│              Docker Container                        │
│  ┌───────────────────────────────────────────────┐  │
│  │     bridge-standalone (port 9876)             │  │
│  │  /thunderbird → Extension (1 client)          │  │
│  │  /mcp → MCP instances (multi-client)          │  │
│  └───────────────────────────────────────────────┘  │
│              ▲                    ▲                  │
│   Thunderbird Extension    docker exec (MCP)        │
└─────────────────────────────────────────────────────┘

Option 2: Standard Setup (without Docker)

  1. Clone the repository:
git clone https://github.com/assistance-micro-design/zileo-mcp-thunderbird.git
cd zileo-mcp-thunderbird
  1. Install dependencies and build:
npm install && npm run build
  1. Install the Thunderbird extension (same procedure as Option 1)

Configuration

MCP Client Configuration (Standard)

Add the following to your MCP client configuration.

Claude Desktop (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "thunderbird": {
      "command": "node",
      "args": ["/path/to/zileo-mcp-thunderbird/server/dist/index.js"],
      "env": {
        "THUNDERBIRD_PORT": "9876",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Any MCP-compatible client can connect using the same command and args pattern. For Zileo Chat, see Use This MCP Server in Zileo Chat.

MCP Client Configuration (Docker)

For Docker deployment, the container runs a standalone WebSocket bridge. MCP clients connect via docker exec:

Claude Desktop:

{
  "mcpServers": {
    "thunderbird": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "zileo-mcp-thunderbird-server",
        "node",
        "dist/index.js"
      ],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Important: The container must be running (docker compose up -d) before starting the MCP client.

The MCP server automatically detects the running bridge and connects as a client. Multiple MCP clients can share the same bridge simultaneously.

Environment Variables

VariableDescriptionDefault
THUNDERBIRD_PORTWebSocket port for Thunderbird connection9876
LOG_LEVELLogging level (debug, info, warn, error)info

A .env.example template is provided — copy it to .env and adjust if needed. Every variable has a safe default.

Use This MCP Server in Zileo Chat

This is a Model Context Protocol (MCP) server. To connect it to Zileo Chat:

Prerequisites: Docker Desktop running, the bridge container started (docker compose up -d), and the Thunderbird extension installed (see Installation).

Docker stdio transport — docker exec into the Compose-managed container

The Compose stack keeps the container alive (stdin_open: true) and Zileo Chat attaches to it:

  1. In Zileo Chat: Settings → MCP → Add server.
  2. Fill in:
    • Name: thunderbird
    • Command / Transport: Docker
    • Args (one per line):
      exec
      -i
      zileo-mcp-thunderbird-server
      node
      dist/index.js
      
    • Env (optional): LOG_LEVEL = info
  3. Save, then Test the connection — the discovered tools appear on the server card.

Zileo Chat hardens the Docker spawn. The invocation must start with run (or exec); global flags before the subcommand are refused. Bind-mount sources must be a named volume or a data sub-directory — host system paths (/etc, /usr, /var, …), the host root, a bare home directory, and the Docker socket are all refused, as are --privileged, --network=host, --device, --cap-add, --gpus, --env-file, --volumes-from, and similar isolation-weakening flags. This server is compatible by design: it runs unprivileged over stdio (-i) with no bind mounts (logs live in the named Docker volume zileo-mcp-thunderbird-logs).

Usage

Starting the Server

cd server
npm start

Or for development with auto-reload:

npm run dev

Available MCP Tools (56 total)

Messages (10 tools)

ToolDescription
thunderbird_messages_searchAdvanced email search with filters (subject, from, to, body, tags, dates)
thunderbird_messages_listList messages in a folder with pagination
thunderbird_messages_list_unreadList unread messages across accounts
thunderbird_messages_list_recentList recent messages globally (all accounts, last N hours)
thunderbird_messages_getGet message details (headers, full, or raw format)
thunderbird_messages_moveMove messages to another folder
thunderbird_messages_copyCopy messages to another folder
thunderbird_messages_deleteDelete messages (trash or permanent)
thunderbird_messages_updateUpdate message properties (read, flagged, tags)
thunderbird_messages_archiveArchive messages

Folders (7 tools)

ToolDescription
thunderbird_folders_listList all folders (hierarchical structure)
thunderbird_folders_getGet folder details
thunderbird_folders_createCreate a new subfolder
thunderbird_folders_renameRename a folder
thunderbird_folders_deleteDelete a folder
thunderbird_folders_moveMove a folder
thunderbird_folders_mark_readMark all messages in folder as read

Contacts (9 tools)

ToolDescription
thunderbird_contacts_searchSearch contacts by query
thunderbird_contacts_listList contacts with pagination
thunderbird_contacts_getGet contact details
thunderbird_contacts_createCreate a new contact (properties or vCard)
thunderbird_contacts_updateUpdate contact properties
thunderbird_contacts_deleteDelete a contact
thunderbird_addressbooks_listList all address books
thunderbird_addressbooks_createCreate a new address book
thunderbird_addressbooks_deleteDelete an address book

Tags (4 tools)

ToolDescription
thunderbird_tags_listList all message tags
thunderbird_tags_createCreate a new tag with color
thunderbird_tags_updateUpdate tag name or color
thunderbird_tags_deleteDelete a tag

Accounts (3 tools)

ToolDescription
thunderbird_accounts_listList all email accounts
thunderbird_accounts_getGet account details
thunderbird_identities_listList account identities (sender addresses)

Compose (8 tools)

ToolDescription
thunderbird_compose_begin_newOpen a new compose window
thunderbird_compose_begin_replyReply to an existing message
thunderbird_compose_begin_forwardForward an existing message
thunderbird_compose_get_detailsGet current compose window details
thunderbird_compose_set_detailsUpdate compose window content
thunderbird_compose_save_draftSave compose as draft
thunderbird_compose_save_templateSave compose as template
thunderbird_compose_sendSend the composed email

Calendar (9 tools) - Experimental

ToolDescription
thunderbird_calendars_listList all calendars
thunderbird_calendars_getGet calendar details
thunderbird_events_searchSearch events by date range and query
thunderbird_events_listList events in a calendar
thunderbird_events_getGet event details
thunderbird_events_createCreate event with attendees and recurrence
thunderbird_events_updateUpdate event properties
thunderbird_events_moveReschedule an event
thunderbird_events_deleteDelete an event

Tasks (6 tools) - Experimental

ToolDescription
thunderbird_tasks_listList tasks with filters
thunderbird_tasks_getGet task details
thunderbird_tasks_createCreate a task with due date and priority
thunderbird_tasks_updateUpdate task properties
thunderbird_tasks_deleteDelete a task
thunderbird_tasks_completeMark task as completed

MCP Resources

URIDescription
thunderbird://accountsList of configured email accounts
thunderbird://inbox/unreadUnread messages (all accounts)
thunderbird://inbox/unread/{accountId}Unread messages (specific account)
thunderbird://folders/{accountId}Folder tree for an account
thunderbird://contacts/recentRecently used contacts
thunderbird://calendar/todayToday's calendar events
thunderbird://calendar/upcomingEvents for next 7 days
thunderbird://tasks/pendingIncomplete tasks

Example Usage with Claude

User: "Montre-moi mes emails non lus d'aujourd'hui"
Claude: [Uses thunderbird_messages_search with date filter and unread:true]

User: "Est-ce que j'ai un rendez-vous aujourd'hui?"
Claude: [Uses thunderbird_events_search with today's date range]

User: "Crée un rendez-vous demain à 14h pour 1 heure"
Claude: [Uses thunderbird_events_create with appropriate parameters]

Development

Project Structure

zileo-mcp-thunderbird/
├── server/                    # MCP server implementation
│   ├── src/
│   │   ├── index.ts          # Entry point
│   │   ├── server.ts         # MCP server configuration
│   │   ├── tools/            # 56 MCP tool implementations
│   │   │   ├── messages.ts   # 10 message tools
│   │   │   ├── folders.ts    # 7 folder tools
│   │   │   ├── contacts.ts   # 9 contact tools
│   │   │   ├── tags.ts       # 4 tag tools
│   │   │   ├── accounts.ts   # 3 account tools
│   │   │   ├── compose.ts    # 8 compose tools
│   │   │   ├── calendar.ts   # 9 calendar tools
│   │   │   └── tasks.ts      # 6 task tools
│   │   ├── resources/        # MCP resource handlers
│   │   ├── websocket/        # WebSocket bridge (server + client modes)
│   │   │   ├── bridge.ts     # Multi-client WebSocket server
│   │   │   └── bridge-client.ts  # Client for connecting to existing bridge
│   │   ├── bridge-standalone.ts  # Standalone bridge for Docker
│   │   ├── types/            # TypeScript definitions
│   │   └── utils/            # Logger, errors
│   └── package.json
├── extension/                 # Thunderbird WebExtension
│   ├── manifest.json         # Manifest V3
│   ├── background.js         # Service worker
│   ├── api/                  # API wrappers
│   │   ├── messages.js
│   │   ├── folders.js
│   │   ├── contacts.js
│   │   ├── accounts.js
│   │   ├── tags.js
│   │   ├── compose.js
│   │   └── calendar.js
│   ├── native-messaging/     # Request handler
│   └── experiments/          # Calendar experimental API
├── docs/                     # Documentation
│   ├── api/                  # API reference
│   └── architecture/         # Architecture docs
└── package.json              # Root monorepo config

Running Tests

npm test

Type Checking

cd server && npm run build

Linting

npm run lint

Documentation

Security

  • WebSocket communication on localhost only
  • Origin validation on WebSocket upgrade (rejects non-local origins with HTTP 403)
  • Host header validation on the auth token endpoint (DNS rebinding guard)
  • Granular Thunderbird permissions model
  • No credentials stored in server memory
  • Input validation with Zod schemas (bounded strings and arrays, datetime format enforcement)
  • WebSocket payload limit (5 MiB)
  • Error responses sanitized (no stack traces or internal details)

See SECURITY.md for the full security policy.

Tool Permission Tiers

All 56 MCP tools are classified into three risk tiers, enforced both by the MCP server and by the WebSocket bridge:

TierToolsDefaultExamples
read23Enabledlist, get, search
modify25Enabledcreate, update, move, copy, archive
destructive8Disableddelete, send

Destructive tools (every *_delete plus compose_send) are disabled by default: enable them per tool in the extension options page (Add-ons Manager > Zileo MCP — Thunderbird > Options), which also offers bulk presets (Read Only, Read + Modify, Enable All). Changes apply immediately — no restart needed.

Note (v1.4.0): the extension now requests the messagesDelete permission so thunderbird_messages_delete actually works. Existing users are prompted to re-approve the extension on update.

Troubleshooting

Connection Issues

If the MCP server cannot connect to Thunderbird:

  1. Verify Thunderbird extension is installed and enabled
  2. Check that Thunderbird is running
  3. Ensure port 9876 is not blocked
  4. Check extension console for errors (Tools > Developer Tools > Error Console)
  5. Review server logs: LOG_LEVEL=debug npm start

Calendar Not Working

The calendar API uses experimental Thunderbird APIs:

  1. Ensure you have Thunderbird 128.0 or higher
  2. Check that Lightning calendar is enabled
  3. Calendar features require experimental API permissions

License

Apache License 2.0 - see LICENSE for the full text.

Copyright 2025-2026 Assistance Micro Design
Licensed under the Apache License, Version 2.0

Third-party dependencies and their licenses are documented in THIRD_PARTY_LICENSES.md. See NOTICE for required attribution.

Support

Contributing

See CONTRIBUTING.md for development setup, code standards, and pull request guidelines.

Please read our Code of Conduct before participating.

Acknowledgments

Third-party licenses are documented in THIRD_PARTY_LICENSES.md.


Assistance Micro Design | GitHub

Ver o original no GitHub

Bom para

Relacionados