feat: add MCP server with full Forward Email API coverage (68 tools)

titanism · titanism · commit b53eda24d295 · 2026-03-05T05:53:19.000-06:00
- bin/mcp-server.js: stdio-based CLI entry point
- lib/index.js: MCP protocol handler (listTools, invokeTool)
- lib/tools.js: all 68 API endpoints as MCP tools
- lib/index.d.ts: TypeScript type definitions
- test/index.test.js: 14 tests covering tool listing, error handling, API auth, and encrypt
- README.md: setup guide, client config examples, full tool reference
- .github/workflows/ci.yml: CI for Node 18/20/22
- XO, Prettier, husky, lint-staged, commitlint, c8, fixpack, remark
- LICENSE (BUSL-1.1)

Tools cover: Account, Logs, Contacts (CardDAV), Calendars (CalDAV),
Calendar Events, Domains (CRUD + verify + S3), Catch-All Passwords,
Domain Invites, Domain Members, Aliases (CRUD + password generation),
Sieve Scripts (API key + alias auth), Emails (outbound SMTP),
Messages (IMAP), Folders (IMAP), and Encrypt.
diff --git a/.commitlintrc.js b/.commitlintrc.js
@@ -0,0 +1 @@
+module.exports = { extends: ['@commitlint/config-conventional'] };
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,22 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'pnpm'
+      - run: pnpm install
+      - run: pnpm test
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+coverage
+.DS_Store
+*.log
diff --git a/.husky/commit-msg b/.husky/commit-msg
@@ -0,0 +1,2 @@
+#!/bin/sh
+npx --no -- commitlint --edit "$1"
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -0,0 +1 @@
+pnpm pre-commit
diff --git a/.lintstagedrc b/.lintstagedrc
@@ -0,0 +1,8 @@
+{
+  "*.{js,json,md,yml,yaml}": [
+    "prettier --write"
+  ],
+  "*.js": [
+    "xo --fix"
+  ]
+}
diff --git a/.prettierignore b/.prettierignore
diff --git a/.remarkrc b/.remarkrc
@@ -0,0 +1,3 @@
+{
+  "plugins": ["preset-lint-recommended"]
+}
diff --git a/.xo-ignore b/.xo-ignore
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,22 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Forward Email LLC
+Licensed Work:        @forwardemail/mcp-server
+                      The Licensed Work is (c) 2025 Forward Email LLC.
+Additional Use Grant: You may make use of the Licensed Work, provided that
+                      you may not use the Licensed Work for an Email Service
+                      that is Competitive with the Licensed Work.
+
+                      A "Competitive" service is a service that offers
+                      email forwarding, email hosting, or email API services
+                      that are substantially similar to those offered by
+                      Forward Email (https://forwardemail.net).
+
+Change Date:          Four years from the date the Licensed Work is published.
+
+Change License:       MIT
+
+For information about alternative licensing arrangements for the Licensed Work,
+please visit: https://forwardemail.net
diff --git a/README.md b/README.md
@@ -0,0 +1,211 @@
+# @forwardemail/mcp-server
+
+[Model Context Protocol](https://github.com/modelcontextprotocol/specification) (MCP) server for [Forward Email](https://forwardemail.net). Connect AI assistants to your inbox.
+
+## Overview
+
+This package provides a local MCP server that wraps the [Forward Email API](https://forwardemail.net/email-api). It lets AI agents (Claude, ChatGPT, Cursor, Windsurf, and others) send email, manage domains, and read your inbox through natural language.
+
+The server runs locally on your machine via `stdio`. Your API key never leaves your device.
+
+## Install
+
+```bash
+npm install -g @forwardemail/mcp-server
+```
+
+Or run directly with `npx`:
+
+```bash
+npx @forwardemail/mcp-server
+```
+
+## Setup
+
+### 1. Get your API key
+
+Log in at <https://forwardemail.net/my-account/security> and copy your API key.
+
+### 2. Set the environment variable
+
+```bash
+export FORWARD_EMAIL_API_KEY=your-api-key
+```
+
+### 3. Configure your AI client
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "forwardemail": {
+      "command": "npx",
+      "args": ["@forwardemail/mcp-server"],
+      "env": {
+        "FORWARD_EMAIL_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "forwardemail": {
+      "command": "npx",
+      "args": ["@forwardemail/mcp-server"],
+      "env": {
+        "FORWARD_EMAIL_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+This server exposes the complete [Forward Email API](https://forwardemail.net/email-api) as MCP tools. Every endpoint is covered.
+
+### Account
+
+- `getAccount` - Get your account details
+- `updateAccount` - Update your account
+
+### Logs
+
+- `downloadLogs` - Download email delivery logs
+
+### Contacts (CardDAV)
+
+- `listContacts` - List all contacts
+- `createContact` - Create a contact
+- `getContact` - Get a contact by ID
+- `updateContact` - Update a contact
+- `deleteContact` - Delete a contact
+
+### Calendars (CalDAV)
+
+- `listCalendars` - List all calendars
+- `createCalendar` - Create a calendar
+- `getCalendar` - Get a calendar by ID
+- `updateCalendar` - Update a calendar
+- `deleteCalendar` - Delete a calendar
+
+### Calendar Events (CalDAV)
+
+- `listCalendarEvents` - List all calendar events
+- `createCalendarEvent` - Create a calendar event
+- `getCalendarEvent` - Get a calendar event by ID
+- `updateCalendarEvent` - Update a calendar event
+- `deleteCalendarEvent` - Delete a calendar event
+
+### Domains
+
+- `listDomains` - List all domains
+- `createDomain` - Create a new domain
+- `getDomain` - Get a domain by ID or name
+- `updateDomain` - Update a domain
+- `deleteDomain` - Delete a domain
+- `verifyDomainRecords` - Verify domain DNS records
+- `verifySmtpRecords` - Verify domain SMTP records
+- `testS3Connection` - Test custom S3 connection for a domain
+
+### Domain Catch-All Passwords
+
+- `listCatchAllPasswords` - List domain-wide catch-all passwords
+- `createCatchAllPassword` - Create a domain-wide catch-all password
+- `deleteCatchAllPassword` - Remove a domain-wide catch-all password
+
+### Domain Invites
+
+- `acceptDomainInvite` - Accept a domain invite
+- `createDomainInvite` - Invite a user to a domain
+- `removeDomainInvite` - Remove a domain invite
+
+### Domain Members
+
+- `updateDomainMember` - Update a domain member role
+- `removeDomainMember` - Remove a member from a domain
+
+### Aliases
+
+- `listAliases` - List aliases for a domain
+- `createAlias` - Create a new alias
+- `getAlias` - Get an alias by ID
+- `updateAlias` - Update an alias
+- `deleteAlias` - Delete an alias
+- `generateAliasPassword` - Generate or set a password for an alias
+
+### Sieve Scripts
+
+- `listSieveScripts` - List Sieve scripts for an alias
+- `createSieveScript` - Create a Sieve script for an alias
+- `getSieveScript` - Get a Sieve script by ID
+- `updateSieveScript` - Update a Sieve script
+- `deleteSieveScript` - Delete a Sieve script
+- `activateSieveScript` - Activate a Sieve script
+
+### Sieve Scripts (Alias Auth)
+
+- `listSieveScriptsAliasAuth` - List Sieve scripts (alias auth)
+- `createSieveScriptAliasAuth` - Create a Sieve script (alias auth)
+- `getSieveScriptAliasAuth` - Get a Sieve script (alias auth)
+- `updateSieveScriptAliasAuth` - Update a Sieve script (alias auth)
+- `deleteSieveScriptAliasAuth` - Delete a Sieve script (alias auth)
+- `activateSieveScriptAliasAuth` - Activate a Sieve script (alias auth)
+
+### Emails (Outbound SMTP)
+
+- `listEmails` - List outbound SMTP emails
+- `sendEmail` - Send an email via outbound SMTP
+- `getEmailLimit` - Get outbound SMTP email sending limit
+- `getEmail` - Get an outbound SMTP email by ID
+- `deleteEmail` - Delete an outbound SMTP email
+
+### Messages (IMAP)
+
+- `listMessages` - List and search messages in a folder
+- `createMessage` - Create a new message (draft)
+- `getMessage` - Get a message by ID
+- `updateMessage` - Update a message
+- `deleteMessage` - Delete a message
+
+### Folders (IMAP)
+
+- `listFolders` - List all folders
+- `createFolder` - Create a new folder
+- `getFolder` - Get a folder by ID
+- `updateFolder` - Update a folder
+- `deleteFolder` - Delete a folder
+
+### Encrypt
+
+- `encryptRecord` - Encrypt a plaintext Forward Email TXT record
+
+## Development
+
+```bash
+git clone https://github.com/forwardemail/mcp-server.git
+cd mcp-server
+pnpm install
+pnpm test
+```
+
+## License
+
+[BUSL-1.1](LICENSE)
+
+## Links
+
+- [Forward Email](https://forwardemail.net)
+- [Forward Email API Docs](https://forwardemail.net/email-api)
+- [MCP Specification](https://github.com/modelcontextprotocol/specification)
+- [MCP Landing Page](https://forwardemail.net/mcp)
diff --git a/bin/mcp-server.js b/bin/mcp-server.js
@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+const {McpServer} = require('../lib/index.js');
+
+const server = new McpServer();
+server.listen();
diff --git a/lib/index.d.ts b/lib/index.d.ts
@@ -0,0 +1,9 @@
+export type McpServerOptions = {
+  apiKey?: string;
+  baseURL?: string;
+};
+
+export class McpServer {
+  constructor(options?: McpServerOptions);
+  listen(): void;
+}
diff --git a/lib/index.js b/lib/index.js
@@ -0,0 +1,63 @@
+const readline = require('node:readline');
+const {getTools} = require('./tools.js');
+
+class McpServer {
+  constructor(options = {}) {
+    this.tools = getTools(options);
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false,
+    });
+  }
+
+  listen() {
+    this.rl.on('line', async (line) => {
+      try {
+        const request = JSON.parse(line);
+        await this.handleRequest(request);
+      } catch (error) {
+        this.sendError(error.message);
+      }
+    });
+  }
+
+  async handleRequest(request) {
+    if (request.type === 'listTools') {
+      return this.sendResponse(request.id, {
+        tools: Object.values(this.tools).map((tool) => tool.toolSpec),
+      });
+    }
+
+    if (request.type === 'invokeTool') {
+      const tool = this.tools[request.name];
+      if (tool) {
+        try {
+          const result = await tool.invoke(request.arguments);
+          return this.sendResponse(request.id, {result});
+        } catch (error) {
+          const errorMessage = error.response?.data?.message || error.message;
+          return this.sendError(errorMessage, request.id);
+        }
+      }
+
+      return this.sendError(`Tool not found: ${request.name}`, request.id);
+    }
+
+    return this.sendError(`Unknown request type: ${request.type}`, request.id);
+  }
+
+  sendResponse(id, payload) {
+    this.send({type: 'toolResponse', id, ...payload});
+  }
+
+  sendError(message, id = null) {
+    this.send({type: 'error', id, message});
+  }
+
+  send(data) {
+    process.stdout.write(JSON.stringify(data) + '\n');
+  }
+}
+
+module.exports = {McpServer};
diff --git a/lib/tools.js b/lib/tools.js
diff --git a/package.json b/package.json
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/test/index.test.js b/test/index.test.js

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+module.exports = { extends: ['@commitlint/config-conventional'] };`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+#!/bin/sh`
	`2`	`+npx --no -- commitlint --edit "$1"`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "plugins": ["preset-lint-recommended"]`
	`3`	`+}`