bluemind-mcp

MCP (Model Context Protocol) server to read and search emails and calendar events from a BlueMind account (built against the BlueMind 5.x REST API).

Read-only: no tool modifies, sends or deletes anything.

Configuration

Three required environment variables:

Variable	Description
BLUEMIND_URL	Server URL, e.g. https://mail.example.com
BLUEMIND_EMAIL	User login (email address)
BLUEMIND_PASSWORD	Password
BLUEMIND_ALLOW_INSECURE_TLS	(optional) 1 to accept self-signed certificates

Authentication goes through POST /api/auth/login; the session authKey is then sent as the X-BM-ApiKey header on every call. The session is renewed automatically when it expires.

Usage

Add this to your MCP client configuration (mcp_config.json, claude_desktop_config.json, etc.):

{
  "mcpServers": {
    "bluemind": {
      "command": "npx",
      "args": ["-y", "github:AlexMili/bluemind-mcp"],
      "env": {
        "BLUEMIND_URL": "https://mail.example.com",
        "BLUEMIND_EMAIL": "john.doe@example.com",
        "BLUEMIND_PASSWORD": "..."
      }
    }
  }
}

Or from a local checkout:

npm install
npm run build

{
  "mcpServers": {
    "bluemind": {
      "command": "node",
      "args": ["/path/to/bluemind-mcp/dist/index.js"],
      "env": {
        "BLUEMIND_URL": "https://mail.example.com",
        "BLUEMIND_EMAIL": "john.doe@example.com",
        "BLUEMIND_PASSWORD": "..."
      }
    }
  }
}

Tools

Mail

• list_mail_folders — list mail folders (INBOX, Sent, …) with their folder_uid.
• search_emails — full-text search (Elasticsearch query_string syntax): invoice, subject:meeting AND from:peter, has:attachments… Searches the whole mailbox by default, or a single folder. Parameters: query, folder_uid?, folder_name?, limit, offset.
• list_recent_emails — latest messages of a folder (default INBOX), with an unread_only option.
• read_email — full message content (folder_uid + item_id as returned by the two tools above): headers, text body (HTML converted to text), attachment list. Option prefer_html.

Calendar

• list_calendars — calendars accessible to the user, with their calendar_uid. The default calendar is calendar:Default:<USERID>.
• search_events — text search over events (POST /api/calendars/{uid}/_search), with an optional date range. Parameters: query, calendar_uid?, date_min?, date_max?, limit, offset.
• list_events — agenda view over a date range (date_min/date_max, YYYY-MM-DD or ISO format). Recurring events are returned as series with their recurrence rule.

Development

npm run dev    # tsc --watch

Quick protocol check without an MCP client:

printf '%s\n%s\n%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
 '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
 | BLUEMIND_URL=... BLUEMIND_EMAIL=... BLUEMIND_PASSWORD=... node dist/index.js

License

MIT