mcp-authentik

[![npm version](https://img.shields.io/npm/v/@samik081/mcp-authentik)](https://www.npmjs.com/package/@samik081/mcp-authentik)
[![Docker image](https://ghcr-badge.egpl.dev/samik081/mcp-authentik/latest_tag?trim=major&label=docker)](https://ghcr.io/samik081/mcp-authentik)
[![License: MIT](https://img.shields.io/npm/l/@samik081/mcp-authentik)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@samik081/mcp-authentik)](https://nodejs.org)

# MCP Authentik

MCP server for [Authentik](https://goauthentik.io/) identity management. Manage users, groups, applications, flows, policies, providers, and more through natural language in Cursor, Claude Code, and Claude Desktop.

## Features

- **297 tools** across **22 categories** covering the complete Authentik API
- **Read-only mode** via `AUTHENTIK_ACCESS_TIER=read-only` for safe monitoring
- **Category filtering** via `AUTHENTIK_CATEGORIES` to expose only the tools you need
- **Type-safe SDK client** via `@goauthentik/api`
- **Docker images** for `linux/amd64` and `linux/arm64` on [GHCR](https://ghcr.io/samik081/mcp-authentik)
- **Remote MCP** via HTTP transport (`MCP_TRANSPORT=http`) using the Streamable HTTP protocol
- **TypeScript/ESM** with full type safety

## API Compatibility

Built for Authentik **2026.5**.

## Quick Start

Run the server directly with npx:

```bash
AUTHENTIK_URL="https://auth.example.com" \
AUTHENTIK_TOKEN="your-api-token" \
npx -y @samik081/mcp-authentik
```

The server validates your Authentik connection on startup and fails immediately with a clear error if credentials are missing or invalid.

### Docker

Run with Docker (stdio transport, same as npx):

```bash
docker run --rm -i \
  -e AUTHENTIK_URL=https://auth.example.com \
  -e AUTHENTIK_TOKEN=your-api-token \
  ghcr.io/samik081/mcp-authentik
```

To run as a remote MCP server with HTTP transport:

```bash
docker run -d -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e AUTHENTIK_URL=https://auth.example.com \
  -e AUTHENTIK_TOKEN=your-api-token \
  ghcr.io/samik081/mcp-authentik
```

The MCP endpoint is available at `http://localhost:3000` and a health check at `http://localhost:3000/health`.

## Configuration

**Claude Code CLI (recommended):**

```bash
# Using npx
claude mcp add --transport stdio authentik \
  --env AUTHENTIK_URL=https://auth.example.com \
  --env AUTHENTIK_TOKEN=your-api-token \
  -- npx -y @samik081/mcp-authentik

# Using Docker
claude mcp add --transport stdio authentik \
  --env AUTHENTIK_URL=https://auth.example.com \
  --env AUTHENTIK_TOKEN=your-api-token \
  -- docker run --rm -i ghcr.io/samik081/mcp-authentik

# Using remote HTTP (connect to a running Docker container or HTTP server)
claude mcp add --transport http authentik http://localhost:3000
```

**JSON config** (works with Claude Code `.mcp.json`, Claude Desktop `claude_desktop_config.json`, Cursor `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "authentik": {
      "command": "npx",
      "args": ["-y", "@samik081/mcp-authentik"],
      "env": {
        "AUTHENTIK_URL": "https://auth.example.com",
        "AUTHENTIK_TOKEN": "your-api-token"
      }
    }
  }
}
```

**Docker (stdio):**

```json
{
  "mcpServers": {
    "authentik": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "AUTHENTIK_URL=https://auth.example.com",
        "-e", "AUTHENTIK_TOKEN=your-api-token",
        "ghcr.io/samik081/mcp-authentik"
      ]
    }
  }
}
```

**Remote MCP** (connect to a running Docker container or HTTP server):

```json
{
  "mcpServers": {
    "authentik": {
      "type": "streamable-http",
      "url": "http://localhost:3000"
    }
  }
}
```

## Access Tiers

Control which tools are available using the `AUTHENTIK_ACCESS_TIER` environment variable:

| Tier | Tools | Description |
|------|-------|-------------|
| `full` (default) | 297 | Read and write -- full control |
| `read-only` | 144 | Read only -- safe for monitoring, no state changes |

- **full**: All 297 tools. Includes creating, updating, and deleting users, groups, applications, flows, providers, and all other resources.
- **read-only**: 144 tools. Listing and viewing resources only. No state changes.

Tools that are not available in your tier are not registered with the MCP server. They will not appear in your AI tool's tool list, keeping the context clean.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AUTHENTIK_URL` | Yes | -- | Authentik instance URL (e.g., `https://auth.example.com`) |
| `AUTHENTIK_TOKEN` | Yes | -- | API token with appropriate permissions |
| `AUTHENTIK_ACCESS_TIER` | No | `full` | `read-only` for read-only tools only, `full` for all tools |
| `AUTHENTIK_CATEGORIES` | No | *(all)* | Comma-separated category allowlist (e.g., `core,admin,flows`) |
| `AUTHENTIK_TOOL_BLACKLIST` | No | *(none)* | Comma-separated list of tool names to exclude (e.g., `authentik_users_delete`) |
| `AUTHENTIK_TOOL_WHITELIST` | No | *(none)* | Comma-separated list of tool names to force-include, bypassing access tier and category filters |
| `DEBUG` | No | `false` | Enable debug logging to stderr |
| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` (default) or `http` |
| `MCP_PORT` | No | `3000` | HTTP server port (only used when `MCP_TRANSPORT=http`) |
| `MCP_HOST` | No | `0.0.0.0` | HTTP server bind address (only used when `MCP_TRANSPORT=http`) |
| `MCP_SESSION_IDLE_TIMEOUT` | No | `1800` | Seconds of inactivity after which an HTTP session is closed and its memory released (sessions with a connected SSE stream are never closed). `0` disables. Only used when `MCP_TRANSPORT=http` |
| `MCP_EXCLUDE_TOOL_TITLES` | No | `false` | Set `true` to omit tool titles from registration (saves tokens) |

### Available Categories

`admin`, `authenticators`, `core`, `crypto`, `endpoints`, `enterprise`, `events`, `flows`, `managed`, `oauth2`, `outposts`, `policies`, `property-mappings`, `providers`, `rac`, `rbac`, `reports`, `root`, `sources`, `ssf`, `stages`, `tenants`

## Tools

mcp-authentik provides 297 tools organized by category. Each tool's Access column shows the minimum tier required: `read-only` (available in both tiers) or `full` (requires `full` tier). The Hints column shows tool behavior: `read-only` (no state changes), `destructive` (modifies existing state), `idempotent` (same result if called twice).

<details>
<summary>Admin (8 tools)</summary>

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `authentik_admin_system_info` | Get system information including HTTP host, runtime environment, server time, and embedded outpost status | read-only | read-only, idempotent |
| `authentik_admin_version` | Get Authentik version information including current version and build hash | read-only | read-only, idempotent |
| `authentik_admin_settings_get` | Get current system settings | read-only | read-only, idempotent |
| `authentik_admin_settings_update` | Update system settings (partial update) | full | destructive, idempotent |
| `authentik_admin_apps` | List installed Django applications in the Authentik instance | read-only | read-only, idempotent |
| `authentik_admin_models` | List all data models available in the Authentik instance | read-only | read-only, idempotent |
| `authentik_admin_version_history` | List Authentik version history entries | read-only | read-only, idempotent |
| `authentik_admin_system_task_trigger` | Trigger all system tasks (e.g., cleanup, cache clear) | full | — |

</details>

<details>
<summary>Authenticators (5 tools)</summary>

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `authentik_authenticators_list` | List all authenticator devices across all types for the current user | read-only | read-only, idempotent |
| `authentik_authenticators_admin_by_type_list` | List authenticator devices of a specific type (admin view) | read-only | read-only, idempotent |
| `authentik_authenticators_admin_by_type_get` | Get a single authenticator device by type and ID (admin view) | read-only | read-only, idempotent |
| `authentik_authenticators_admin_by_type_delete` | Delete an authenticator device by type and ID (admin view) | full | destructive |
| `authentik_authenticators_user_by_type_list` | List authenticator devices of a specific type for the current user | read-only | read-only, idempotent |

</details>

<details>
<summary>Core (45 tools)</summary>

**Users**

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `authentik_users_list` | List users with optional filters for username, email, name, active status, superuser status, path, groups, and search | read-only | read-only, idempotent |
| `authentik_users_get` | Get a single user by their numeric ID | read-only | read-only, idempotent |
| `authentik_users_create` | Create a new user | full | — |
| `authentik_users_update` | Update an existing user (partial update) | full | destructive, idempotent |
| `authentik_users_delete` | Delete a user by their numeric ID | full | destructive |
| `authentik_users_me` | Get information about the currently authenticated user | read-only | read-only, idempotent |
| `authentik_users_set_password` | Set a new password for a user | full | destructive, idempotent |
| `authentik_users_create_service_account` | Create a new service account user with an optional associated group and token | full | — |
| `authentik_users_generate_recovery_link` | Generate a temporary recovery link for a user to regain account access | full | — |
| `authentik_users_send_recovery_email` | Send a recovery email to a user using a specified email stage | full | — |
| `authentik_users_list_paths` | List all user paths configured in the system | read-only | read-only, idempotent |
| `authentik_users_account_lockdown` | Lock down a user account, deactivating it and terminating its active sessions | full | destructive |
| `authentik_users_