mcp-ory-kratos

MCP server enabling AI assistants to manage Ory Kratos identities, sessions, and authentication flows. Built for developers integrating identity management into Claude Code, GitHub Copilot, or Gemini CLI workflows.

Table of Contents

• Prerequisites
• Installation
• Configuration
• Environment Variables
• Claude Code
• GitHub Copilot (VS Code)
• Gemini CLI
• Quick Start
• Tool Reference
• Identity Tools
• Session Tools
• Courier Tools
• Recovery Tools
• Analytics Tools
• Health Tools
• Behaviour
• Pagination
• Credential Redaction
• Destructive Tools and Confirmation
• Resources
• Usage Examples
• Breaking changes in 0.3.0
• Troubleshooting
• Development
• Contributing
• Support
• License

Prerequisites

• Ory Kratos instance running with Admin API access (developed and tested against v26.2.0; the integration suite pins that version)
• Node.js 20+ or Bun 1.x installed
• One of the supported MCP clients:
• Claude Code 1.0+
• VS Code 1.99+ with GitHub Copilot (GA in 1.102+)
• Gemini CLI 0.1+

Note: Kratos deployment and configuration is out of scope for this MCP server. See the Ory Kratos documentation for deployment guidance.

Installation

Install via npm or run directly with npx:

# Using npm
npm install -g mcp-ory-kratos

# Using npx (no installation required)
npx mcp-ory-kratos

# Using bun
bun add -g mcp-ory-kratos

Configuration

Environment Variables

Boolean variables accept 1, true, yes, on (case-insensitive); anything else is false.

Admin URL: The Kratos SDK appends /admin/... to the base URL itself. Trailing slashes are stripped, and if KRATOS_ADMIN_URL already ends in /admin (common behind a reverse proxy, e.g. https://ory.example.com/kratos/admin) that suffix is removed for SDK calls so paths do not become /admin/admin/.... Both http://localhost:4434 and http://localhost:4434/admin work.

Note: This MCP server can run alongside other MCP servers in your configuration. Each server operates independently.

Claude Code

Add to ~/.claude.json for global configuration:

{
  "mcpServers": {
    "kratos": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-ory-kratos"],
      "env": {
        "KRATOS_ADMIN_URL": "http://localhost:4434"
      }
    }
  }
}

For project-scoped configuration, create .mcp.json in your project root:

{
  "mcpServers": {
    "kratos": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-ory-kratos"],
      "env": {
        "KRATOS_ADMIN_URL": "http://localhost:4434"
      }
    }
  }
}

GitHub Copilot (VS Code)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "kratos": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-ory-kratos"],
      "env": {
        "KRATOS_ADMIN_URL": "http://localhost:4434"
      }
    }
  }
}

For secrets handling with input variables:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "kratos-url",
      "description": "Kratos Admin API URL",
      "password": false
    }
  ],
  "servers": {
    "kratos": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-ory-kratos"],
      "env": {
        "KRATOS_ADMIN_URL": "${input:kratos-url}"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json for global configuration:

{
  "mcpServers": {
    "kratos": {
      "command": "npx",
      "args": ["-y", "mcp-ory-kratos"],
      "env": {
        "KRATOS_ADMIN_URL": "http://localhost:4434"
      }
    }
  }
}

For project-scoped configuration, create .gemini/settings.json in your project:

{
  "mcpServers": {
    "kratos": {
      "command": "npx",
      "args": ["-y", "mcp-ory-kratos"],
      "env": {
        "KRATOS_ADMIN_URL": "http://localhost:4434"
      }
    }
  }
}

Quick Start

1. Configure Your MCP Client

Choose your MCP client from the Configuration section above and add the appropriate configuration.

2. Verify Installation

Start your MCP client and verify the tools are available:

• Claude Code: Run /mcp to see available servers
• VS Code: Click the tools icon in Copilot Chat
• Gemini CLI: The server starts automatically when tools are needed

3. Try Your First Command

Ask your AI assistant:

"List all identities in Kratos"

The MCP server will execute kratos_list_identities and return the results.

Tool Reference

27 tools, grouped by toolset (enable/disable groups with KRATOS_TOOLSETS). Kind is the MCP annotation: read-only tools survive KRATOS_READ_ONLY=1; destructive tools change or remove data and trigger a confirmation prompt (see Behaviour).

Identity Tools

Toolset: identities

Session Tools

Toolset: sessions

Courier Tools

Toolset: courier

Recovery Tools

Toolset: recovery

Recovery links and codes are equivalent to full account takeover. Treat them as secrets.

Analytics Tools

Toolset: analytics

Both scan up to maxPages pages and report pagesScanned / truncated.

Health Tools

Toolset: health

Behaviour

Every tool declares an outputSchema and returns its result as structuredContent alongside the JSON text; errors come back as isError results with { code, message, kratosStatus?, suggestion? }.

Pagination

List tools take pageSize (1-100, default 20) and pageToken, and return { items, count, nextPageToken }. nextPageToken is absent on the last page; pass it back as pageToken to continue. Tokens are opaque cursors bound to the Kratos instance.

Tools that walk many pages (analytics, kratos_list_sessions with filter) accept maxPages (default KRATOS_MAX_SCAN_PAGES) and return pagesScanned and truncated. When truncated is true the page cap was hit; raise maxPages or pass the returned nextPageToken back as pageToken to resume from the first unscanned page (both analytics tools accept pageToken; an analytics aggregate then covers only the resumed range).

Credential Redaction

When includeCredential is requested, the config of secret-bearing credential types (password, oidc, saml, totp, lookup_secret, webauthn, passkey) is replaced with "[redacted: set KRATOS_ALLOW_CREDENTIAL_EXPOSURE=1]". Type, identifiers, version and timestamps are kept so an agent can still see what is linked. Set KRATOS_ALLOW_CREDENTIAL_EXPOSURE=1 to return the raw config.

Destructive Tools and Confirmation

Tools annotated destructiveHint (delete, disable, update, patch, set state) ask the client to confirm via MCP elicitation before doing anything. If the user declines, the tool returns { cancelled: true } and nothing is changed. Clients without elicitation support skip the prompt (the annotation still lets them warn on their own). Disable the prompt with KRATOS_CONFIRM_DESTRUCTIVE=0, or hide destructive tools entirely with KRATOS_READ_ONLY=1.

Resources

Usage Examples

List Identities

List all identities in Kratos

Find User by Email

Find the identity with email [email protected]

Check Kratos Health

Is Kratos healthy and ready?

View Active Sessions

Show all active sessions in Kratos

Get Session Analytics

What authentication methods are users using? Show session analytics.

Create Recovery Link

Create a recovery link for user with ID abc-123

Breaking changes in 0.3.0

0.3.0 is a minor bump (the package is pre-1.0) that changes several contracts. Update clients and scripts as follows:

Additive changes (no action needed): every tool now carries a title, MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint: false), an output schema and structuredContent; list tools return { items, count, nextPageToken? }; kratos_delete_identity_sessions returns sessionsExisted, kratos_set_identity_state returns sessionsRevoked; new env vars KRATOS_TOOLSETS, KRATOS_READ_ONLY, KRATOS_CONFIRM_DESTRUCTIVE, KRATOS_ALLOW_CREDENTIAL_EXPOSURE, KRATOS_MAX_SCAN_PAGES are all optional.

Troubleshooting

Connection refused

Symptom: ECONNREFUSED or connection timeout errors

Solutions:

1. Verify Kratos is running: curl http://localhost:4434/health/alive
2. Check KRATOS_ADMIN_URL is correct (use Admin API port, typically 4434)
3. Ensure Kratos Admin API is accessible from the MCP server's network

401 Unauthorized

Symptom: Authentication errors when calling Kratos API

Solutions:

1. If Kratos requires authentication, set KRATOS_AUTH_TYPE=api-key
2. Provide KRATOS_API_KEY with a valid API key
3. For custom auth, use KRATOS_AUTH_TYPE=custom-headers with KRATOS_CUSTOM_HEADERS

Tool not found

Symptom: MCP client doesn't show Kratos tools

Solutions:

1. Restart your MCP client after configuration changes
2. Verify configuration file syntax (valid JSON)
3. Check file location matches your client's expected path
4. Run npx mcp-ory-kratos manually to verify the server starts

Timeout errors

Symptom: Requests timeout before completing

Solutions:

1. Increase KRATOS_TIMEOUT_MS (default: 30000ms)
2. Check network latency to Kratos instance
3. Verify Kratos isn't overloaded or unresponsive

Development

Local Setup

# Clone the repository
git clone https://github.com/feedback-loop-ai/mcp-ory-kratos.git
cd mcp-ory-kratos

# Install dependencies
bun install

# Start the MCP server
bun run start

Build Commands

# Lint (Biome)
bun run lint
bun run lint:fix  # Auto-fix issues

# Type check (src + tests)
bun run typecheck

# Unit tests (hermetic, with coverage) - this is what CI runs
bun run test:unit

# Dependency audit (high severity and above)
bun run audit

# Build the distributable
bun run build

Integration Tests

The integration suite in tests/api/ runs against a real Kratos (pinned to v26.2.0, configured from tests/kratos/). Start one with Docker and run the suite:

docker compose up -d --wait
bun run test:api
docker compose down

To target another instance, copy .env.test.local.example to .env.test.local and set KRATOS_ADMIN_URL / KRATOS_EXPECTED_VERSION (the suite fails fast on a version mismatch). Override the container version with KRATOS_VERSION=v26.x.y docker compose up -d.

CI runs lint, type check, audit and unit tests on every push and PR, plus the integration job against the docker-compose Kratos.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Run lint, type check and tests (bun run lint && bun run typecheck && bun run test:unit)
5. Commit your changes (git commit -m 'Add my feature')
6. Push to your branch (git push origin feature/my-feature)
7. Open a Pull Request

Support

If you find this project useful, consider sponsoring its development:

Your support helps maintain and improve the MCP Ory Kratos server.

License

MIT