@aimbitgmbh/kerio-connect-mcp

v0.2.1

Published

13 days ago

MCP server for Kerio Connect - Mail, Calendar, Contacts, Tasks, and Notes management

Kerio Connect MCP Server

A Model Context Protocol (MCP) server providing programmatic access to Kerio Connect for Mail, Calendar, Contacts, Tasks, and Notes management.

Tested and optimized for Qwen 3.8 27B tool calling

The server accepts standards-compliant MCP arguments and also normalizes common OpenAI-compatible tool-call serialization issues, such as numbers, booleans, or arrays returned as JSON strings. This keeps strict validation in place while making tool execution reliable with Qwen.

Prerequisites

Node.js >= 18.0.0
Kerio Connect server with API access
Valid Kerio Connect credentials (email and password)

Features

Mail management (read, search, send, draft, move, organize)
Calendar events with recurrence support
Contact management with full vCard support
Task management
Notes organization
Dynamic folder discovery
Full-text search across modules
TypeScript implementation with Zod validation

Installation

NPM Package

npx @aimbitgmbh/kerio-connect-mcp

MCP Client Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "kerio-connect": {
      "command": "npx",
      "args": ["-y", "@aimbitgmbh/kerio-connect-mcp"],
      "env": {
        "KERIO_SERVER": "https://mail.example.com",
        "KERIO_USERNAME": "[email protected]",
        "KERIO_PASSWORD": "your-password"
      }
    }
  }
}

Configuration

Required Environment Variables

| Variable | Description | |----------|-------------| | KERIO_SERVER | Kerio Connect server URL (e.g., https://mail.example.com) | | KERIO_USERNAME | Your email address | | KERIO_PASSWORD | Your password |

Optional Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | KERIO_VERIFY_SSL | Verify SSL certificates | false | | KERIO_ENABLE_SEND | Enable email sending without review | false |

Note: Email sending is disabled by default for safety. When disabled, the server creates drafts only.

Environment File Example

Create a .env file in the project root:

# Kerio Connect server URL (required)
KERIO_SERVER=https://mail.example.com

# Your email address (required)
[email protected]

# Your password (required)
KERIO_PASSWORD=your-password-here

# Verify SSL certificates (optional, default: false)
KERIO_VERIFY_SSL=false

# Enable email sending without manual review (optional, default: false)
KERIO_ENABLE_SEND=false

Available Tools

Mail Module

mails_list - List emails with filtering
mails_get - Get email by ID with full content
mails_show_recent - View recent emails
mails_search - Full-text search
mails_send - Send email (requires KERIO_ENABLE_SEND=true)
mails_save_draft - Create draft email
mails_update_draft - Edit draft
mails_move - Move emails to folder
mails_mark_read - Mark as read/unread
mails_flag - Flag/unflag emails
mails_delete - Delete emails

Calendar Module

calendars_list - List events with date filtering
calendars_search - Search events
calendars_create - Create events with recurrence
calendars_update - Update event details
calendars_delete - Delete events

Calendar discovery includes personal, shared, and public calendars. When multiple calendars have the same name, select one with owner/calendar, owner-email/calendar, or its full folder ID.

Model Compatibility Test

The repository includes an opt-in live test for OpenAI-compatible model APIs. It checks tool selection, argument typing, email-recipient arrays, and qualified shared-calendar selection without connecting to Kerio or changing Kerio data.

MCP_MODEL_TEST_BASE_URL="https://your-model-endpoint.example/v1" \
MCP_MODEL_TEST_API_KEY="your-api-key" \
MCP_MODEL_TEST_MODEL="your-model-name" \
npm run test:model

The API key is read from the process environment only and is never written by the test script.

Contacts Module

contacts_list - List contacts
contacts_get - Get contact details
contacts_create - Create contact
contacts_update - Update contact
contacts_search - Search contacts
contacts_delete - Delete contact

Tasks Module

tasks_list - List tasks
tasks_create - Create task
tasks_complete - Mark complete
tasks_update - Update task
tasks_search - Search tasks
tasks_delete - Delete task

Notes Module

notes_list - List notes
notes_search - Search notes
notes_count - Count notes
notes_create - Create note
notes_move - Move note
notes_update - Edit note
notes_delete - Delete note

Folder Management

folders_list - List all folders
folders_create - Create folder

Architecture

Project Structure

kerio-connect-mcp/
├── src/
│   ├── index.ts       # MCP server
│   ├── client.ts      # Kerio API client
│   ├── config.ts      # Configuration
│   ├── tools.ts       # Tool definitions
│   └── types.ts       # Type definitions
└── dist/              # Compiled output

Troubleshooting

Configuration Validation Failed

Ensure all required environment variables are set:

KERIO_SERVER
KERIO_USERNAME
KERIO_PASSWORD

Invalid Credentials

Verify that your username is your full email address and test login via the Kerio Connect web interface.

SSL Certificate Errors

For self-signed certificates, set KERIO_VERIFY_SSL=false.

Session Expired

The server automatically re-authenticates. If errors persist, verify credentials are valid and the server is accessible.

Security

Credentials passed via environment variables only
Email sending disabled by default
Server binds to localhost via stdio
Configurable SSL certificate verification
Automatic session management

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an issue for bugs, feature requests, or improvements.

License

See LICENSE file for details.