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
• Usage Examples
• Troubleshooting
• Development
• Contributing
• Support
• License

Prerequisites

• Ory Kratos instance running with Admin API access
• Node.js 18+ 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

Variable	Required	Default	Description
KRATOS_ADMIN_URL	Yes	-	Kratos Admin API base URL (e.g., http://localhost:4434)
KRATOS_AUTH_TYPE	No	none	Authentication type: none, api-key, or custom-headers
KRATOS_API_KEY	Conditional	-	Required when KRATOS_AUTH_TYPE=api-key
KRATOS_CUSTOM_HEADERS	Conditional	-	JSON object of headers when KRATOS_AUTH_TYPE=custom-headers
KRATOS_TIMEOUT_MS	No	30000	Request timeout in milliseconds
LOG_LEVEL	No	info	Log level: trace, debug, info, warn, error

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

Identity Tools

Tool	Description
kratos_list_identities	List identities with optional filtering by credential identifier (e.g., email)
kratos_get_identity	Get detailed information about a specific identity by ID
kratos_get_identity_by_external_id	Look up identity by external identifier
kratos_create_identity	Create a new identity with schema, traits, and optional metadata
kratos_update_identity	Full update of an identity (replaces all fields)
kratos_patch_identity	Partial update using JSON Patch operations
kratos_delete_identity	Permanently delete an identity and all associated data
kratos_delete_identity_credential	Delete a specific credential type from an identity

Session Tools

Tool	Description
kratos_list_sessions	List all sessions with optional filtering by active status
kratos_get_session	Get session details by ID
kratos_list_identity_sessions	List all sessions for a specific identity
kratos_disable_session	Revoke/disable a session (log user out)
kratos_extend_session	Extend session expiration time
kratos_delete_identity_sessions	Delete all sessions for an identity

Courier Tools

Tool	Description
kratos_list_courier_messages	List emails/SMS sent by Kratos with delivery status
kratos_get_courier_message	Get courier message details including delivery attempts

Recovery Tools

Tool	Description
kratos_create_recovery_link	Generate account recovery link for a user
kratos_create_recovery_code	Generate account recovery code for a user

Analytics Tools

Tool	Description
kratos_session_analytics	Aggregated session statistics (auth methods, devices, browsers)
kratos_credential_analytics	Authentication method adoption statistics and MFA rates

Health Tools

Tool	Description
kratos_health_alive	Check if Kratos server is alive and accepting requests
kratos_health_ready	Check if Kratos is ready (database connectivity, dependencies)
kratos_version	Get Kratos server version

Usage Examples

List Identities

List all identities in Kratos

Find User by Email

Find the identity with email user@example.com

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

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
bun x tsc --noEmit

# Run unit tests
bun x vitest run --config tests/vitest.config.ts --dir tests/unit

# Run all tests (requires Kratos - see .env.test.local.example)
bun run test

# Run tests with coverage
bun run test -- --coverage.enabled

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 and tests (bun run lint && bun run test)
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