Install and run

Independent integration for SimpleLogin

simplelogin-mcp is an independent, open-source project. It is not an official SimpleLogin or Proton AG product, service, or MCP implementation, and it is not affiliated with, endorsed by, or sponsored by SimpleLogin or Proton AG.

Looking for SimpleLogin’s official service? Visit SimpleLogin.

Start with the MCP client you already use. For a client and server on the same machine, local stdio is the smallest trust boundary and does not open a network listener. Direct Node.js — Streamable HTTP and Docker Compose — Streamable HTTP remain available when you need a persistent service.

Prerequisites

• A SimpleLogin account with a dedicated API key.
• Git, which the installation commands use to clone the repository.
• Docker with Docker Compose, or Node.js 24.x with Corepack and pnpm 11.5.1.
• An MCP client that supports local stdio or Streamable HTTP.

Treat the API key like a password

SL_API_KEY grants full SimpleLogin account control. Create a dedicated key, never commit it, and revoke it at SimpleLogin if it leaks.

Common path

Follow these steps in order. The detailed installation and client recipes appear below.

1. Create the API key. Create a dedicated SimpleLogin API key for this server. Keep it private and separate from prompts or source control.

2. Build or start the server. For Local stdio, clone the repository, install dependencies, and run pnpm build before writing the client configuration. For Direct Node.js — Streamable HTTP or Docker Compose — Streamable HTTP, follow the matching installation below and start the service first.

3. Configure the client. Choose its recipe below. Point Local stdio clients at the absolute path to the built dist/index.js; point Streamable HTTP clients at the running /mcp endpoint.

4. Restart and verify. Reload the MCP client, confirm that simplelogin-mcp connects and its tools are discovered, then use the supplied read-only account-usage prompt to verify the complete path.

Protect Streamable HTTP

The startup guard refuses Docker Compose and non-loopback binds without MCP_AUTH_TOKEN unless the explicit unsafe override is enabled. Supported deployments keep the token rather than bypassing the guard.

Choose a deployment shape

All three shapes expose the same catalog. Choose based on where the client and server should live, not on which tools you need.

Docker Compose

Docker Compose — Streamable HTTP quick start

git clone https://github.com/enthouan/simplelogin-mcp.git
cd simplelogin-mcp
cp .env.example .env
# Set SL_API_KEY and MCP_AUTH_TOKEN in .env
${EDITOR:-vi} .env
grep -Eq '^SL_API_KEY=.+$' .env || { echo 'Set SL_API_KEY in .env before starting.' >&2; exit 1; }
grep -Eq '^MCP_AUTH_TOKEN=.+$' .env || { echo 'Set MCP_AUTH_TOKEN in .env before starting.' >&2; exit 1; }
docker compose up -d
docker compose ps
curl http://localhost:3000/health

Compose listens on 0.0.0.0:3000 inside the container, publishes only to 127.0.0.1 by default, and the normal startup guard requires MCP_AUTH_TOKEN. Only the explicit unsafe override bypasses that guard.

Read the complete Docker Compose — Streamable HTTP guide →

Direct Node.js

Direct Node.js — Streamable HTTP on loopback

git clone https://github.com/enthouan/simplelogin-mcp.git
cd simplelogin-mcp
corepack enable
pnpm install --filter simplelogin-mcp --frozen-lockfile
cp .env.example .env
# Keep TRANSPORT=http, HOST=127.0.0.1, and PORT=3000; set SL_API_KEY in .env
${EDITOR:-vi} .env
grep -Eq '^SL_API_KEY=.+$' .env || { echo 'Set SL_API_KEY in .env before starting.' >&2; exit 1; }
pnpm build
# Load the file without putting the key in shell history or the parent shell
(
  set -a
  . ./.env
  set +a
  pnpm start
)

Connect to POST http://127.0.0.1:3000/mcp. A direct loopback run does not require MCP_AUTH_TOKEN. The server refuses a wider bind without it unless the explicit unsafe override is enabled; supported wider deployments use the token and TLS.

Read the complete Direct Node.js — Streamable HTTP guide →

Local stdio

Local stdio configuration

{
  "mcpServers": {
    "simplelogin": {
      "command": "node",
      "args": ["/absolute/path/to/simplelogin-mcp/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "SL_API_KEY": "sl-your-key-here"
      }
    }
  }
}

This JSON illustrates Claude Desktop's stdio shape; other clients use different configuration formats. Run pnpm install --filter simplelogin-mcp --frozen-lockfile && pnpm build first. Stdio does not use MCP_AUTH_TOKEN; keep the client config private because it contains your API key. Use the recipe for your MCP client.

Read the complete Local stdio guide →

Configure your client

These recipes configure Codex, Claude Code, Claude Desktop, VS Code, or OpenCode. Each includes the same low-data, read-only verification prompt.

Codex

Codex reads MCP servers from its TOML configuration and can forward an already exported API key without storing its value in that shared file.

Where to configure it: Export SL_API_KEY, then add this table to ~/.codex/config.toml.

~/.codex/config.toml

[mcp_servers.simplelogin]
command = "node"
args = ["/absolute/path/to/simplelogin-mcp/dist/index.js"]
default_tools_approval_mode = "writes"
env_vars = ["SL_API_KEY"]

[mcp_servers.simplelogin.env]
TRANSPORT = "stdio"

Protect the SimpleLogin API key

Export SL_API_KEY before launching Codex. env_vars forwards it to the child process without storing its value in TOML. The writes approval mode asks before tools that are not marked read-only.

Reload the client: Restart the Codex client, then open the MCP server list or use /mcp to confirm that simplelogin is connected.

Configuration syntax: Codex MCP documentation.

Verify it works

After the client discovers the server, use this low-data, read-only check:

Read-only verification prompt

Can you show me my SimpleLogin account usage?

Expected result

The expected tool is account_get_stats. Confirm that it is marked read-only before approving it. It takes no arguments and returns aggregate account counts without changing SimpleLogin. Those counts still pass through the client and its configured model.

Claude Code

Claude Code expands environment variables in project-scoped .mcp.json files, so the shared file can reference a machine-specific checkout and secret without containing either value.

Where to configure it: Set SIMPLELOGIN_MCP_ROOT and SL_API_KEY in the environment that starts Claude Code, then create .mcp.json at the project root.

.mcp.json

{
  "mcpServers": {
    "simplelogin": {
      "type": "stdio",
      "command": "node",
      "args": ["${SIMPLELOGIN_MCP_ROOT}/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "SL_API_KEY": "${SL_API_KEY}"
      }
    }
  }
}

Protect the SimpleLogin API key

The file contains only environment-variable references and can be shared. Keep the environment source for SL_API_KEY private and out of version control.

Reload the client: Start a new Claude Code session, run /mcp, and confirm that simplelogin is connected. claude mcp list also reports missing environment variables.

Configuration syntax: Claude Code MCP documentation.

Verify it works

After the client discovers the server, use this low-data, read-only check:

Read-only verification prompt

Can you show me my SimpleLogin account usage?

Expected result

The expected tool is account_get_stats. Confirm that it is marked read-only before approving it. It takes no arguments and returns aggregate account counts without changing SimpleLogin. Those counts still pass through the client and its configured model.

Claude Desktop

Until simplelogin-mcp is distributed as a desktop extension package, Claude Desktop can launch the locally built server as a developer-defined stdio process.

Where to configure it: Open Settings → Developer → Edit Config and add this entry to claude_desktop_config.json.

claude_desktop_config.json

{
  "mcpServers": {
    "simplelogin": {
      "command": "node",
      "args": ["/absolute/path/to/simplelogin-mcp/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "SL_API_KEY": "sl-your-key-here"
      }
    }
  }
}

Protect the SimpleLogin API key

This developer configuration contains the SimpleLogin API key. Keep the file private; do not paste it into an issue or support request.

Reload the client: Quit and reopen Claude Desktop. Open Connectors from the chat composer or Developer settings to check the server status and tools.

Configuration syntax: MCP local server guide.

Verify it works

After the client discovers the server, use this low-data, read-only check:

Read-only verification prompt

Can you show me my SimpleLogin account usage?

Expected result

The expected tool is account_get_stats. Confirm that it is marked read-only before approving it. It takes no arguments and returns aggregate account counts without changing SimpleLogin. Those counts still pass through the client and its configured model.

VS Code

VS Code input variables can request the API key when the server first starts and store it without placing the value directly in mcp.json.

Where to configure it: Run MCP: Open User Configuration from the Command Palette and replace its contents or merge these inputs and server entries.

User profile mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "simplelogin-api-key",
      "description": "SimpleLogin API key",
      "password": true
    }
  ],
  "servers": {
    "simplelogin": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/simplelogin-mcp/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "SL_API_KEY": "${input:simplelogin-api-key}"
      }
    }
  }
}

Protect the SimpleLogin API key

The password input keeps the actual API key out of mcp.json. Use the user configuration unless you intentionally want to share a credential-free workspace definition.

Reload the client: Run MCP: List Servers, select simplelogin, and start or restart it. Review the server configuration before accepting VS Code’s trust prompt.

Configuration syntax: VS Code MCP configuration reference.

Verify it works

After the client discovers the server, use this low-data, read-only check:

Read-only verification prompt

Can you show me my SimpleLogin account usage?

Expected result

The expected tool is account_get_stats. Confirm that it is marked read-only before approving it. It takes no arguments and returns aggregate account counts without changing SimpleLogin. Those counts still pass through the client and its configured model.

OpenCode

OpenCode defines local servers under mcp.servers and can read the SimpleLogin API key from the environment instead of a tracked project file.

Where to configure it: Save this as opencode.json in the project or ~/.config/opencode/opencode.json for global use.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "simplelogin": {
        "type": "local",
        "command": [
          "node",
          "/absolute/path/to/simplelogin-mcp/dist/index.js"
        ],
        "environment": {
          "TRANSPORT": "stdio",
          "SL_API_KEY": "{env:SL_API_KEY}"
        }
      }
    }
  }
}

Protect the SimpleLogin API key

Keep the environment that supplies SL_API_KEY private. Configuration guidance is not a live interoperability claim; check the compatibility matrix for current evidence.

Reload the client: Relaunch OpenCode and run opencode2 mcp list. OpenCode does not currently promise hot reload after direct configuration edits.

Configuration syntax: OpenCode MCP documentation.

Verify it works

After the client discovers the server, use this low-data, read-only check:

Read-only verification prompt

Can you show me my SimpleLogin account usage?

Expected result

The expected tool is account_get_stats. Confirm that it is marked read-only before approving it. It takes no arguments and returns aggregate account counts without changing SimpleLogin. Those counts still pass through the client and its configured model.

The local stdio and Streamable HTTP recipes are configuration guidance. See the compatibility matrix for current retained client evidence and unavailable routes.

Next

• Docker Compose — Streamable HTTP for the published-image operator path.
• Direct Node.js — Streamable HTTP for a persistent loopback service.
• Local stdio for desktop and command-line MCP clients.
• Get a SimpleLogin API key before configuring any installation.
• Client setup for the full recipes and official documentation links.
• Operations for inspection, upgrades, rollback, credential rotation, and shutdown.
• Security & Data before widening network access.