simplelogin-mcp
Provides tools for managing SimpleLogin aliases and mailboxes via the SimpleLogin REST API, including validating account access, listing and retrieving aliases, creating random or custom aliases, updating alias notes and names, toggling or deleting aliases, listing mailboxes, and retrieving alias creation options.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@simplelogin-mcp create a random email alias for newsletter signups"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| — | Validate the API key and return account info ( |
|
| List aliases, newest first ( |
|
| Fetch a single alias by numeric ID. |
|
| Get signed suffixes and mailbox IDs needed for a custom alias ( |
|
| Create a random alias ( |
|
| Create a chosen-prefix alias ( |
|
| Change an alias's note and/or name. |
|
| Flip an alias between enabled and disabled. |
|
| Delete an alias. This cannot be undone. |
| — | List available 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:
Create a 1Password item holding the SimpleLogin API key.
Set
SIMPLELOGIN_OP_ITEMto its item ID and, optionally,SIMPLELOGIN_OP_VAULTto its vault name (default:Hermes Agent).~/.hermes/.envis sourced so non-interactive MCP processes see these.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 simpleloginRestart 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 -qUnit 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
Authenticationheader 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_aliasandsl_toggle_aliaschange live state — check the target alias before calling them.
Licence
MIT — see LICENSE.
Available Tools
10 toolssl_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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Private email aliases that forward to your inbox: create, find, edit and turn aliases off or on.
Manage anon.li email aliases, recipients and encrypted file drop metadata over OAuth.
Give AI agents secure access to your email via private aliases with dedicated mailbox storage.
Email, calendar and contacts for AI agents: Gmail, Microsoft 365 and IMAP accounts behind one API.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables natural language management of email aliases via EmailAlias.io API, including create, update, delete, and monitoring tasks.1338 npmMIT
- AlicenseAqualityDmaintenanceEnables 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.316 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseAqualityCmaintenanceEnables email management and masked email alias administration over JMAP, with a draft-first safety default and optional HTML footer signature.12MIT