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

Related MCP server: enterprise-auth-mcp-server

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

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

Session Tools

Courier Tools

Recovery Tools

Analytics Tools

Health Tools

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