Skip to main content
Glama
simplelogin-mcp

simplelogin-mcp

by codepilots

simplelogin-mcp

A stdio MCP server that exposes SimpleLogin alias management as tools for Hermes (or any MCP client). It is a thin wrapper around SimpleLogin's public REST API; the API key stays in the server subprocess environment and is never written to a config file, chat, or the repository.

API endpoints follow the upstream docs: https://github.com/simple-login/app/blob/master/docs/api.md

Tools

Tool

Arguments

Description

sl_whoami

—

Validate the API key and return account info (GET /user_info).

sl_list_aliases

query?, page_id=0

List aliases, newest first (GET /v2/aliases).

sl_get_alias

alias_id

Fetch a single alias by numeric ID.

sl_alias_options

hostname?

Get signed suffixes and mailbox IDs needed for a custom alias (GET /v5/alias/options). Pass a site hostname for site-specific suffixes.

sl_create_alias

note?, mode?

Create a random alias (POST /alias/random/new). mode may be uuid, word, or omitted for the default.

sl_create_custom_alias

alias_prefix, signed_suffix, mailbox_ids, note?, name?, hostname?

Create a chosen-prefix alias (POST /v3/alias/custom/new). Get signed_suffix and mailbox_ids from sl_alias_options first.

sl_update_alias

alias_id, note?, name?

Change an alias's note and/or name.

sl_toggle_alias

alias_id

Flip an alias between enabled and disabled.

sl_delete_alias

alias_id

Delete an alias. This cannot be undone.

sl_list_mailboxes

—

List available mailboxes (GET /v2/mailboxes).

Errors from the API are returned as clean MCP tool errors (no raw stack traces or echoed credentials). Every ID used in a URL path is URL-escaped.

Related MCP server: MCP-postale.io

Install

Requires Python 3.11+ and the MCP SDK.

cd /path/to/simplelogin-mcp
uv venv
uv pip install -e .

Credentials

The client reads SIMPLELOGIN_API_KEY at request time. The recommended launcher is bin/simplelogin-mcp, which fetches the key from 1Password with op at startup and exports it only into the child process:

  1. Create a 1Password item holding the SimpleLogin API key.

  2. Set SIMPLELOGIN_OP_ITEM to its item ID and, optionally, SIMPLELOGIN_OP_VAULT to its vault name (default: Hermes Agent). ~/.hermes/.env is sourced so non-interactive MCP processes see these.

  3. Launch through the wrapper: bin/simplelogin-mcp.

The wrapper probes common field labels (password, credential, api key, token) and falls back to a JSON field scan, so the exact label does not matter. If you rotate the key in 1Password, restart the MCP server process to pick it up — no file edits needed.

You can also bypass 1Password by exporting SIMPLELOGIN_API_KEY yourself, but never place it in a committed file or paste it into chat.

SIMPLELOGIN_API_BASE optionally overrides the default https://api.simplelogin.io/api (useful for a local mock).

Hermes registration

hermes mcp add simplelogin --command /absolute/path/to/simplelogin-mcp/bin/simplelogin-mcp
hermes mcp test simplelogin

Restart Hermes after adding or changing the server so the tools load into your session. Other MCP clients can use the same command over stdio.

Development

uv pip install -e . pytest
.venv/bin/python -m pytest -q

Unit tests mock HTTP and never require a live key. They cover auth headers, endpoint paths, request bodies, error detail scrubbing, and tool registration.

Security notes

  • The API key is sent only in the Authentication header to the configured API base; it never appears in a URL or log message.

  • No credential, item ID, or vault name is baked into the source; all are supplied via environment variables at runtime.

  • sl_delete_alias and sl_toggle_alias change live state — check the target alias before calling them.

Licence

MIT — see LICENSE.

Available Tools

10 tools
sl_alias_optionsA

Get the signed suffixes and mailboxes available for creating a custom alias. Pass hostname (e.g. 'example.com') for a site-specific suffix.

Inputs: hostname.

sl_create_aliasC

Create a new random alias. note is a label for your own use.

Inputs: mode, note.

sl_create_custom_aliasB

Create a custom alias with a chosen prefix. Get signed_suffix and mailbox_ids from sl_alias_options first.

Inputs: mailbox_ids (required), alias_prefix (required), signed_suffix (required), name, +2 more.

sl_delete_aliasA

Delete a SimpleLogin alias by ID. This cannot be undone.

Inputs: alias_id (required).

sl_get_aliasB

Get one SimpleLogin alias by numeric ID.

Inputs: alias_id (required).

sl_list_aliasesC

List aliases (newest first), optionally filtered by a search query.

Inputs: query, page_id.

sl_list_mailboxesB

List the mailboxes available for SimpleLogin aliases.

Inputs: no named parameters.

sl_toggle_aliasB

Flip a SimpleLogin alias between enabled and disabled by ID.

Inputs: alias_id (required).

sl_update_aliasC

Update the note and/or name of an existing SimpleLogin alias.

Inputs: alias_id (required), name, note.

sl_whoamiA

Check the configured API key and return the SimpleLogin account email.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 10 tools

    Disambiguation4/5

    Each tool maps to a distinct action on aliases or mailboxes, and the create_alias (random) vs create_custom_alias (chosen prefix) split is explicitly documented. Minor overlap remains between sl_alias_options and sl_list_mailboxes, since alias options returns mailbox IDs and mailboxes are listed separately, which could cause a selection fumble.

    Naming Consistency4/5

    All names use a consistent sl_ prefix and snake_case with verb_noun form (sl_create_alias, sl_list_aliases, sl_delete_alias). A few deviate into noun-only or idiosyncratic forms (sl_alias_options, sl_whoami), but the pattern remains readable and predictable.

    Tool Count5/5

    Ten tools is well within the ideal range, and each one earns its place: CRUD on aliases, a toggle, an options helper, a mailbox listing, and an auth check. No redundant or filler tools are present.

    Completeness4/5

    The alias lifecycle is fully covered with list, get, create (random and custom), update, toggle, and delete, plus discovery helpers and authentication verification. Gaps exist around mailbox management (creation/deletion) and alias contacts/notes-level operations, but the core workflow is closed.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables natural language management of email aliases via EmailAlias.io API, including create, update, delete, and monitoring tasks.
      13
      38 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables managing postale.io email hosting through the official API, covering domains, DNS/DKIM, mailboxes, aliases, branding, Sieve filters, quotas, and logs, with safety confirmations for destructive operations.
      31
      6 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables safe, multi-account Gmail and Microsoft 365 operations with explicit aliases, including searching, reading, drafting, archiving, labels/categories, and human-reviewed sending via a localhost approval window.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables email management and masked email alias administration over JMAP, with a draft-first safety default and optional HTML footer signature.
      12
      MIT