fagents-mcp

fagents-mcp

MCP (Model Context Protocol) server exposing email tools to Claude Code agents. Handles SMTP sending and IMAP reading, with per-agent credential isolation and an audit-logged secure email gate.

Stack: TypeScript, Node.js, Express, @modelcontextprotocol/sdk. Stateless MCP over HTTP.

---

Tools

| Tool | Description | |------|-------------| | send_email | Send email via SMTP. Supports plain text, HTML, CC/BCC, and file attachments. | | list_emails | List messages in a mailbox folder. Returns newest first with envelope metadata. | | read_email | Read a full message by UID — body text/HTML and attachment list. | | search_emails | Search by from/to/subject/date range/unseen/body text. | | list_mailboxes | List available IMAP folders. | | download_attachment | Download an attachment by part number. Returns base64-encoded content. | | gate_email | Secure read: fetches email via IMAP, logs full content to #email-log channel (human-visible audit trail), returns metadata to caller. Set read_body=true to also receive body — content is always logged first. Use this for all inbound email access. |

---

Architecture

Claude agent (MCP client)
  │  POST /mcp  (x-api-key: <agent-token>)
  ▼
fagents-mcp (Express + MCP SDK)
  ├─ auth.ts     — resolve agent from API key
  ├─ config.ts   — load per-agent env from agents.json, AsyncLocalStorage context
  ├─ email.ts    — SMTP send via nodemailer
  ├─ imap.ts     — IMAP read/search/download via node-imap
  └─ server.ts   — MCP tool registration, gate_email audit logging

Stateless: Each MCP request creates a fresh server+transport instance. No session state between calls.

Per-agent credentials: Each agent sends its unique API key. The server resolves the agent ID, then loads that agent's credentials (SMTP host/pass, IMAP host/pass, etc.) from agents.json via AsyncLocalStorage. Agents never see each other's credentials.

---

Credential Storage

Credentials live in agents.json in the working directory (typically the installation directory). This file is managed by the human operator — agents must not read or write it directly.

{
  "agents": {
    "ftf": {
      "apiKey": "<hashed-or-raw-key>",
      "SMTP_HOST": "smtp.example.com",
      "SMTP_USER": "ftf@example.com",
      "SMTP_PASS": "...",
      "IMAP_HOST": "imap.example.com",
      "IMAP_USER": "ftf@example.com",
      "IMAP_PASS": "...",
      "COMMS_TOKEN": "...",
      "COMMS_URL": "http://127.0.0.1:9754"
    }
  },
  "shared": {
    "SMTP_PORT": "587",
    "IMAP_PORT": "993"
  }
}

AgentConfig accepts any [envKey: string]: string pairs alongside apiKey — the schema is open for extension (Telegram tokens, etc.).

---

Environment Variables

Without agents.json, the server falls back to environment variables:

| Variable | Default | Description | |----------|---------|-------------| | MCP_PORT | 3000 | Listen port | | MCP_HOST | 127.0.0.1 | Bind address | | MCP_API_KEY | — | Single-agent API key (if not using agents.json) | | SMTP_HOST | — | SMTP server hostname | | SMTP_PORT | 587 | SMTP port | | SMTP_USER | — | SMTP username | | SMTP_PASS | — | SMTP password | | SMTP_FROM | SMTP_USER | From address | | IMAP_HOST | — | IMAP server hostname | | IMAP_PORT | 993 | IMAP port | | IMAP_USER | — | IMAP username | | IMAP_PASS | — | IMAP password | | IMAP_TLS | true | Use TLS for IMAP | | COMMS_URL | — | fagents-comms URL (for gate_email audit log) | | COMMS_TOKEN | — | Comms token (for gate_email audit log) |

---

Setup

npm install
npm run build        # compiles TypeScript → dist/

# Single-agent mode (env vars)
MCP_API_KEY=secret SMTP_HOST=smtp.example.com ... node dist/server.js

# Multi-agent mode (agents.json in working dir)
node dist/server.js

Development (no build step):

npm run dev          # runs src/server.ts directly via tsx

---

Claude Code Integration

Add to .claude/settings.json (or via MCP config):

{
  "mcpServers": {
    "fagents-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-api-key": "<your-agent-api-key>"
      }
    }
  }
}

MCP tools are discovered at session start. After changing tools or restarting the server, start a new Claude session to pick up changes.

---

Security Notes

• gate_email strips <untrusted> tag variants from email body before wrapping content — prevents boundary escape attacks from malicious emails.
• Subject and messageId are excluded from gate_email response (attacker-controlled fields that could carry injection payloads). They are logged to #email-log for human review.
• agents.json should be chmod 600 and never committed to version control.
• Server binds 127.0.0.1 by default. Use SSH tunnels or a reverse proxy for remote access.

---

Origin

Part of the fagents project — autonomous Claude Code agent infrastructure. Built by freeturtle agents and Juho Muhonen.