Skip to main content
Glama
smailr-mcp

smailr-mcp

smailr-mcp

English · 中文


English

An open-source MCP (Model Context Protocol) server for Smailr mail. It lets any MCP-compatible AI client — Claude Desktop, Cursor, Cherry Studio, Cline, … — read, search and send email through natural language.

Local-first: the server runs on your machine over stdio. Your API key never leaves your computer.

Features

23 tools covering the full Smailr API:

Group

Tools

Mailboxes

list_mailboxes · create_mailbox · check_address · get_mailbox · update_mailbox · delete_mailbox

Mails

list_mails · get_mail · update_mail · delete_mail · search_mails · send_mail

Attachments

upload_attachment

Contacts

list_contacts · create_contact

Folders

list_folders · create_folder

Labels

list_labels · create_label

Read-only

list_rules · list_signatures · get_quota · get_stats

Requirements

  • Node.js ≥ 18

  • A Smailr account

Step 1 — Get an API key

Pick one of the two ways:

Option A — manual: Smailr web console → Settings → Developer → create an API key (nm_...).

Option B — NodeLoc OAuth (no settings page needed):

npx -y smailr-mcp auth

This opens your browser for NodeLoc authorization. After authorizing, the browser lands on a smailr.com page (it may show an error — that's expected); copy the full URL from the address bar and paste it back into the terminal. The CLI then creates a scoped API key for you and prints a ready-to-paste client config.

Step 2 — Configure your MCP client

{
  "mcpServers": {
    "smailr": {
      "command": "npx",
      "args": ["-y", "smailr-mcp"],
      "env": { "SMAILR_API_KEY": "nm_your_key_here" }
    }
  }
}

Config file locations:

  • Claude Desktop: claude_desktop_config.json

  • Cursor: Settings → MCP

  • Cherry Studio / Cline: add a custom MCP server with the same JSON

Restart the client, then ask things like:

Environment variables

Variable

Required

Description

SMAILR_API_KEY

yes

Your Smailr API key (nm_...)

SMAILR_BASE_URL

no

API base URL override (default https://smailr.com/api/v1)

Development

git clone <repo-url>
cd smailr-mcp
npm install
npm run build
node test-stdio.mjs   # smoke test: MCP handshake + tools/list

Notes & limitations

  • The Smailr API defines no response schemas in its OpenAPI spec, so tool outputs are passed through as raw JSON.

  • Contacts/folders/labels support list + create only (no update/delete in the upstream API); rules and signatures are read-only.

  • There is no webhook/push mechanism upstream; new-mail workflows require polling list_mails.

License

MIT


Related MCP server: phison-mail-mcp

中文

一个开源的 MCP(Model Context Protocol)服务器,把 Smailr 邮箱接入任何支持 MCP 的 AI 客户端——Claude Desktop、Cursor、Cherry Studio、Cline 等。装上之后,直接用自然语言收发、搜索、管理邮件。

本地优先:服务器以 stdio 方式运行在你自己的电脑上,API key 不经过任何第三方服务器。

功能

23 个工具,覆盖 Smailr 全部 API:邮箱管理(6)、邮件读写/搜索/发送(6)、附件上传(1)、联系人(2)、文件夹(2)、标签(2)、只读接口(收信规则、签名、配额、统计,共 4)。

环境要求

  • Node.js ≥ 18

  • 一个 Smailr 账号

第一步:获取 API key(二选一)

方式 A — 手动:Smailr 控制台 → 设置 → 开发者 → 创建 API key(nm_...)。

方式 B — NodeLoc OAuth 登录(不用进设置页):

npx -y smailr-mcp auth

命令会自动打开浏览器进行 NodeLoc 授权。授权完成后浏览器会跳到一个 smailr.com 页面(可能显示报错,属正常现象);把地址栏里的完整 URL 复制粘贴回终端,CLI 会自动为你创建一把 scoped API key,并打印出可直接复制的客户端配置。

第二步:配置 MCP 客户端

{
  "mcpServers": {
    "smailr": {
      "command": "npx",
      "args": ["-y", "smailr-mcp"],
      "env": { "SMAILR_API_KEY": "nm_你的key" }
    }
  }
}
  • Claude Desktop:写入 claude_desktop_config.json

  • Cursor:设置 → MCP

  • Cherry Studio / Cline:添加自定义 MCP server,填入同样的 JSON

重启客户端后即可直接对话:

  • "列出我收件箱最新的 5 封邮件"

  • "用 hello@我的域名 给 alice@example.com 发封邮件"

  • "我的存储配额用了多少?"

环境变量

变量

必填

说明

SMAILR_API_KEY

是

Smailr API key(nm_...)

SMAILR_BASE_URL

否

API 地址覆盖(默认 https://smailr.com/api/v1)

本地开发

git clone <仓库地址>
cd smailr-mcp
npm install
npm run build
node test-stdio.mjs   # 冒烟测试:MCP 握手 + 工具列表

已知限制

  • Smailr 的 OpenAPI 文档未定义响应 schema,工具输出为原始 JSON 透传

  • 联系人/文件夹/标签上游只支持列出和创建;收信规则和签名为只读

  • 上游没有 webhook 推送机制,新邮件场景需要轮询 list_mails

开源协议

MIT

Available Tools

23 tools
check_addressA

Check whether a mailbox address is available. Scope: mailbox:read

Inputs: address (required).

create_contactB

Create a contact. Scope: contact:write

Inputs: name (required), email (required).

create_folderB

Create a folder in a mailbox. Scope: folder:write

Inputs: name (required), mailbox_id (required).

create_labelC

Create a label. Scope: tag:write

Inputs: name (required), color.

create_mailboxB

Create a new mailbox. Scope: mailbox:write

Inputs: local_part (required), domain_id.

delete_mailC

Delete a mail. Scope: mail:manage

Inputs: id (required).

delete_mailboxB

Delete a mailbox permanently. Scope: mailbox:write

Inputs: id (required).

get_mailA

Get full details of a single mail. Scope: mail:read

Inputs: id (required).

get_mailboxA

Get mailbox details by ID. Scope: mailbox:read

Inputs: id (required).

get_quotaA

Get storage quota usage. Scope: storage:read

Inputs: no named parameters.

get_statsB

Get account statistics. Scope: storage:read

Inputs: no named parameters.

list_contactsB

List contacts. Scope: contact:read

Inputs: no named parameters.

list_foldersA

List folders of a mailbox. Scope: folder:read

Inputs: mailbox_id (required).

list_labelsA

List labels. Scope: tag:read

Inputs: no named parameters.

list_mailboxesA

List all Smailr mailboxes. Scope: mailbox:read

Inputs: no named parameters.

list_mailsB

List mails in a mailbox, optionally filtered by folder. Scope: mail:read

Inputs: mailbox_id (required), page, folder, per_page.

list_rulesA

List incoming-mail filter rules. Scope: filter:read

Inputs: no named parameters.

list_signaturesA

List mail signatures. Scope: signature:read

Inputs: no named parameters.

search_mailsA

Full-text search across mails. Scope: mail:read

Inputs: q (required).

send_mailC

Send an email from a mailbox. Scope: mail:send

Inputs: to (required), mailbox_id (required), cc, bcc, +5 more.

update_mailA

Update mail state (e.g. read/unread, flags, folder). Scope: mail:manage

Inputs: id (required), patch (required).

update_mailboxB

Update a mailbox (settings such as display name, signature, etc.). Scope: mailbox:write

Inputs: id (required), patch (required).

upload_attachmentA

Upload a local file as a mail attachment; returns an attachment ID for send_mail. Scope: attachment:write

Inputs: file_path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools are clearly resource-action pairs, but get_quota and get_stats both cover storage/account usage and list_mails/search_mails could be confused when searching a single mailbox. These are minor boundary cases; the rest are distinct.

    Naming Consistency5/5

    All tools use lowercase snake_case verb_noun names (list_, create_, get_, update_, delete_, search_, send_, upload_, check_). Naming is uniform and predictable across all 23 tools.

    Tool Count3/5

    23 tools is within the heavy range for an MCP server. The email domain is broad enough to justify many of them, but the count feels slightly bloated because several resource areas have only partial operations.

    Completeness2/5

    Mailboxes and mails have solid lifecycle coverage, but contacts, labels, and folders only support list/create, while rules and signatures are read-only. Agents cannot update or delete these secondary resources, which is a significant gap for full email management.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables users to manage email accounts via IMAP/SMTP, including reading, searching, sending emails with attachments and calendar invites, all through natural language interactions with MCP-compatible clients.
      1
      36 PyPI
      4
      MIT
    • F
      license
      B
      quality
      C
      maintenance
      Enables AI models to send, receive, search, and manage emails via SMTP/IMAP, including support for attachments, contacts, and advanced search.
      18
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects any IMAP/SMTP mailbox to AI agents via MCP, enabling email read, search, send, reply, and management through natural language.
      11 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Connects MCP clients to any IMAP/SMTP email account, enabling email search, reading, sending, replying, forwarding, flagging, moving, and folder management via natural language.
      17
      MIT