llng-mcp

MCP Server for Lemonldap-NG

Manage your Lemonldap-NG web SSO instances from Claude, Cursor, or any MCP-compatible AI assistant. 43 tools covering configuration, sessions, OIDC, SAML, 2FA, and more.

Quick Start

1. Add to Claude Code

claude mcp add llng-mcp -- npx llng-mcp

Or add to Claude Desktop (~/.claude/desktop_config.json):

{
  "mcpServers": {
    "llng": {
      "command": "npx",
      "args": ["llng-mcp"]
    }
  }
}

2. Configure your SSO instances

Create ~/.llng-mcp.json:

{
  "instances": {
    "prod": {
      "mode": "ssh",
      "ssh": { "host": "sso.example.com", "user": "root" }
    },
    "staging": {
      "mode": "ssh",
      "ssh": { "host": "sso-staging.example.com", "user": "root" }
    }
  },
  "default": "prod"
}

All tools accept an optional instance parameter to target a specific instance. See Configuration below for SSH, API, Kubernetes, and Docker modes.

3. Start using

Just ask Claude in natural language:

• "Show me the current SSO configuration"
• "How many active sessions are there?"
• "List all OIDC relying parties"
• "Add a new OIDC RP for my-app with redirect URI https://my-app.example.com/callback"
• "Delete all sessions for user jdoe"
• "What 2FA devices does user alice have?"
• "Rotate the OIDC signing keys"
• "Export the full configuration as backup"

What You Can Do

| Capability | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------ | | Configuration | Read, update, export, import, merge, and rollback SSO configuration. Test email settings. | | Sessions | Search, inspect, modify, and delete user sessions. Backup all sessions. Manage offline/refresh tokens. | | OIDC Relying Parties | Enable the OIDC issuer, list/add/update/delete relying parties with sensible defaults. | | OIDC Testing | Full OIDC flow testing: discovery, authorization with PKCE, token exchange, userinfo, introspection. | | SAML Federation | Download IdP metadata, import SAML federations. | | Two-Factor Auth | List and manage users' 2FA devices (TOTP, U2F, WebAuthn). | | User Consents | List and revoke OIDC consents per user. | | User Directory | Look up user attributes from the configured backend. | | Cache & Maintenance | Purge central and local caches, rotate OIDC keys, delete sessions by UID pattern. | | Multi-Instance | Manage multiple SSO instances (prod, staging, dev) from a single server. |

Installation

Requires Node.js 20 or higher.

npm install llng-mcp
npm run build

Configuration

The MCP server reads configuration from ~/.llng-mcp.json with support for environment variable overrides. Two operation modes are available.

SSH/CLI Mode (Default)

Execute commands via SSH or locally using Lemonldap-NG CLI tools.

{
  "mode": "ssh",
  "ssh": {
    "binPrefix": "/usr/share/lemonldap-ng/bin"
  }
}

For remote SSH connections:

{
  "mode": "ssh",
  "ssh": {
    "host": "llng.example.com",
    "user": "root",
    "port": 22,
    "sudo": "root",
    "binPrefix": "/usr/share/lemonldap-ng/bin"
  }
}

remoteCommand - Execute via Docker, LXC, etc.

The remoteCommand field inserts a command between SSH/sudo and the LLNG CLI binary. This allows running commands inside containers or through other wrappers:

{
  "mode": "ssh",
  "ssh": {
    "host": "server.example.com",
    "remoteCommand": "docker exec sso-auth-1",
    "binPrefix": "/usr/share/lemonldap-ng/bin"
  }
}

This produces: ssh server.example.com docker exec sso-auth-1 /usr/share/lemonldap-ng/bin/lemonldap-ng-cli ...

binPrefix - Custom binary location

The binPrefix field (default: /usr/share/lemonldap-ng/bin) sets the base directory for all LLNG CLI tools. Individual paths (cliPath, sessionsPath, configEditorPath) can still override specific binaries.

SSH Mode Limitations: The following operations require API mode:

• llng_2fa_list - List 2FA devices
• llng_2fa_delete - Remove 2FA devices
• llng_2fa_delType - Remove all devices of type
• llng_consent_list - List user consents
• llng_consent_delete - Revoke consents

API Mode

Call REST endpoints on LLNG manager with optional HTTP Basic authentication.

{
  "mode": "api",
  "api": {
    "baseUrl": "https://manager.example.com/api/v1",
    "basicAuth": {
      "username": "admin",
      "password": "secret"
    },
    "verifySsl": true
  }
}

Kubernetes Mode

Execute commands inside Kubernetes pods using kubectl exec. The server automatically resolves a pod from a Deployment using label selectors.

{
  "mode": "k8s",
  "k8s": {
    "context": "prod-cluster",
    "namespace": "auth",
    "deployment": "lemonldap-ng",
    "container": "sso"
  }
}

• context (optional) - kubectl context to use
• namespace (required) - Kubernetes namespace
• deployment (required) - Deployment name (used to derive the default pod selector app.kubernetes.io/name=DEPLOYMENT)
• container (optional) - Container name within the pod (omit if single container)
• podSelector (optional) - Override the label selector for pod resolution (default: app.kubernetes.io/name=DEPLOYMENT)
• binPrefix (optional) - Path to LLNG binaries inside the pod (default: /usr/share/lemonldap-ng/bin)

K8s mode has the same limitations as SSH mode (2FA and consents require API mode).

OIDC Configuration (Optional)

For OIDC testing tools:

{
  "oidc": {
    "issuer": "https://auth.example.com",
    "clientId": "my-app",
    "clientSecret": "secret",
    "redirectUri": "http://localhost:8080/callback",
    "scope": "openid profile email"
  }
}

Multi-Instance Configuration

To manage multiple LLNG instances from a single MCP server, use the instances format:

{
  "instances": {
    "prod": {
      "mode": "api",
      "api": {
        "baseUrl": "https://manager-prod.example.com/api/v1",
        "basicAuth": { "username": "admin", "password": "secret" }
      }
    },
    "staging": {
      "mode": "ssh",
      "ssh": {
        "host": "staging.example.com",
        "user": "root"
      }
    },
    "local": {
      "mode": "ssh"
    }
  },
  "default": "prod"
}

• instances - Named LLNG instance configurations, each with its own mode, ssh, api, and oidc settings
• default - Name of the instance used when the instance parameter is omitted (defaults to the first instance if not specified)
• All tools accept an optional instance parameter to target a specific instance
• The legacy flat format (without instances) is fully supported and treated as a single "default" instance
• Environment variables (LLNG_*) apply to the default instance only

Environment Variables

Configuration can be overridden via environment variables:

Mode

• LLNG_MODE - Set to "ssh" or "api"

SSH Configuration

• LLNG_SSH_HOST - Hostname for SSH connection
• LLNG_SSH_USER - SSH username
• LLNG_SSH_PORT - SSH port (default: 22)
• LLNG_SSH_SUDO - User to sudo to
• LLNG_SSH_REMOTE_COMMAND - Command inserted between SSH/sudo and LLNG binaries (e.g., docker exec container-name)
• LLNG_SSH_BIN_PREFIX - Base directory for LLNG CLI tools (default: /usr/share/lemonldap-ng/bin)
• LLNG_SSH_CLI_PATH - Path to lemonldap-ng-cli (overrides binPrefix)
• LLNG_SSH_SESSIONS_PATH - Path to lemonldap-ng-sessions (overrides binPrefix)
• LLNG_SSH_CONFIG_EDITOR_PATH - Path to lmConfigEditor (overrides binPrefix)

Kubernetes Configuration

• LLNG_K8S_CONTEXT - kubectl context
• LLNG_K8S_NAMESPACE - Kubernetes namespace
• LLNG_K8S_DEPLOYMENT - Deployment name
• LLNG_K8S_CONTAINER - Container name (optional)
• LLNG_K8S_POD_SELECTOR - Label selector override
• LLNG_K8S_BIN_PREFIX - Path to LLNG binaries inside the pod

API Configuration

• LLNG_API_URL - API base URL
• LLNG_API_BASIC_USER - HTTP Basic Auth username
• LLNG_API_BASIC_PASSWORD - HTTP Basic Auth password
• LLNG_API_VERIFY_SSL - Set to "false" to skip SSL verification

OIDC Configuration

• LLNG_OIDC_ISSUER - OIDC issuer URL
• LLNG_OIDC_CLIENT_ID - OIDC client ID
• LLNG_OIDC_CLIENT_SECRET - OIDC client secret
• LLNG_OIDC_REDIRECT_URI - OIDC redirect URI
• LLNG_OIDC_SCOPE - OIDC scopes

Note: When using multi-instance configuration, environment variables override the default instance only.

Usage with Claude Desktop

Add this to your Claude Desktop configuration (~/.claude/desktop_config.json):

{
  "mcpServers": {
    "llng": {
      "command": "node",
      "args": ["/path/to/llng-mcp/dist/index.js"]
    }
  }
}

If you have configuration in ~/.llng-mcp.json, it will be automatically loaded. You can also override via environment variables:

{
  "mcpServers": {
    "llng": {
      "command": "node",
      "args": ["/path/to/llng-mcp/dist/index.js"],
      "env": {
        "LLNG_MODE": "api",
        "LLNG_API_URL": "https://manager.example.com/api/v1"
      }
    }
  }
}

Usage with Other MCP Clients

Inspect Tool with npx

Test the server using the official MCP inspector:

npx @modelcontextprotocol/inspector node dist/index.js

This opens an interactive inspector where you can call tools and see results.

Configuration

Configure your MCP client to connect to the stdio server. For example, with cline:

{
  "mcpServers": {
    "llng": {
      "command": "node",
      "args": ["/absolute/path/to/llng-mcp/dist/index.js"]
    }
  }
}

Tools Reference

Note: All tools accept an optional instance parameter (string) to target a specific LLNG instance. When omitted, the default instance is used.

Configuration Management

| Tool | Description | Parameters | Mode | | ------------------------ | -------------------- | --------------------------- | ------- | | llng_config_info | Get config metadata | None | Both | | llng_config_get | Fetch config values | keys (string[]) | Both | | llng_config_set | Update config values | keys (object), log (string) | Both | | llng_config_addKey | Add composite key | key, subkey, value | Both | | llng_config_delKey | Delete composite key | key, subkey | Both | | llng_config_export | Export as JSON | None | Both | | llng_config_import | Import from JSON | json (string) | Both | | llng_config_merge | Merge JSON | json (string) | Both | | llng_config_rollback | Revert previous | None | Both | | llng_config_update_cache | Force cache refresh | None | Both | | llng_config_test_email | Send test email | destination (string) | SSH/K8s |

Session Management

| Tool | Description | Parameters | Mode | | ------------------- | ----------------- | ---------------------------------------------------------------------------- | ---- | | llng_session_get | Get session | id, backend, persistent, hash, refreshTokens | Both | | llng_session_search | Search sessions | where, select, backend, count, kind, persistent, hash, idOnly, refreshTokens | Both | | llng_session_delete | Delete sessions | ids (optional), where, kind, backend, persistent, hash, refreshTokens | Both | | llng_session_setKey | Modify session | id, keys, backend, persistent, hash, refreshTokens | Both | | llng_session_delKey | Remove attributes | id, keys, backend, persistent, hash, refreshTokens | Both | | llng_session_backup | Export sessions | backend, persistent, refreshTokens | Both |

Two-Factor Authentication

| Tool | Description | Parameters | Mode | | ---------------- | -------------- | -------------------- | -------- | | llng_2fa_list | List devices | user (string) | API Only | | llng_2fa_delete | Remove devices | user, ids (string[]) | API Only | | llng_2fa_delType | Remove by type | user, type (string) | API Only |

User Consents

| Tool | Description | Parameters | Mode | | ------------------- | --------------- | -------------------- | -------- | | llng_consent_list | List consents | user (string) | API Only | | llng_consent_delete | Revoke consents | user, ids (string[]) | API Only |

Instance Discovery

| Tool | Description | Parameters | Mode | | -------------- | ------------------------ | ---------- | ---- | | llng_instances | List available instances | None | Both |

OIDC Relying Party Management

| Tool | Description | Parameters | Mode | | ----------------------- | ------------------ | ---------------------------------------------------------------------------------------------- | ---- | | llng_oidc_issuer_enable | Enable OIDC issuer | force (optional bool) | Both | | llng_oidc_rp_list | List OIDC RPs | None | Both | | llng_oidc_rp_get | Get RP details | confKey | Both | | llng_oidc_rp_add | Add new RP | confKey, clientId, redirectUris, clientSecret, displayName, exportedVars, extraClaims, options | Both | | llng_oidc_rp_delete | Delete RP | confKey | Both |

CLI Utilities

| Tool | Description | Parameters | Mode | | --------------------------- | ------------------------ | ----------------------------------------------------------------------- | ------- | | llng_download_saml_metadata | Download SAML metadata | url, outputFile, noCheck, verbose | SSH/K8s | | llng_import_metadata | Import SAML federation | url, spPrefix, idpPrefix, ignoreSp, ignoreIdp, remove, noCheck, verbose | SSH/K8s | | llng_delete_session | Delete sessions by UID | uid, force, debug | SSH/K8s | | llng_user_attributes | Look up user attributes | username, field | SSH/K8s | | llng_purge_central_cache | Purge central cache | debug, force, json | SSH/K8s | | llng_purge_local_cache | Purge local cache | debug | SSH/K8s | | llng_rotate_oidc_keys | Rotate OIDC signing keys | debug | SSH/K8s |

OIDC Testing

| Tool | Description | Parameters | Requires Config | | -------------------- | --------------- | ---------------------- | --------------- | | llng_oidc_metadata | Fetch discovery | None | OIDC config | | llng_oidc_authorize | Get auth URL | scope (optional) | OIDC config | | llng_oidc_tokens | Exchange code | code, code_verifier | OIDC config | | llng_oidc_userinfo | Get user info | access_token (string) | OIDC config | | llng_oidc_introspect | Inspect token | token (string) | OIDC config | | llng_oidc_refresh | Refresh token | refresh_token (string) | OIDC config | | llng_oidc_whoami | Decode ID token | id_token (string) | OIDC config | | llng_oidc_check_auth | Test protected | url, access_token | OIDC config |

Development

Build

npm run build

Watch Mode

npm run dev

Unit Tests

npm test

Integration Tests

Requires Docker Compose for running Lemonldap-NG instance:

npm run test:integration

The test stack includes a full Lemonldap-NG instance accessible at http://localhost:19876.

View test configuration in docker-compose.test.yml.

Architecture

llng-mcp uses an abstraction layer (ILlngTransport) with two implementations:

• SshTransport - Executes CLI commands via SSH or locally using child_process
• K8sTransport - Executes CLI commands inside Kubernetes pods via kubectl exec
• ApiTransport - Makes HTTP requests to LLNG REST API

A TransportRegistry manages transport instances per named configuration, enabling multi-instance support. All tools resolve their transport through the registry, allowing seamless switching between modes and instances.

Limitations

SSH Mode

2FA management and user consent operations require the REST API. The CLI tools (lemonldap-ng-cli and lemonldap-ng-sessions) provide read-only or delete-only capabilities for these features.

API Mode

Ensure the LLNG manager is properly configured with REST endpoints enabled and authentication credentials provided.

OIDC Tools

OIDC testing tools are optional. Omit OIDC configuration if not needed.

License

AGPL-3.0

Copyright: 2026 LINAGORA

See the Lemonldap-NG project for more information.