OAuth Callback

OAuth CallbackBrowser sign-in for CLI tools and desktop apps

Capture an authorization code on a loopback redirect URI in Node.js, Deno and Bun, with a one-line browser provider for the MCP SDK

Get Started
Migrate from v2
View on GitHub
OAuth Callback Demo
  • 🚀

    Node.js, Deno and Bun

    One node:http listener on Node.js 22+, Deno 2 and Bun 1.2+.

  • 🔌

    Ephemeral loopback ports

    Binds 127.0.0.1 on a free port (RFC 8252) and hands you the redirect URI. No port collisions, no port config.

  • 🛡️

    Secure by default

    A state on every flow, strict callback and URL validation, neutral pages with security headers.

  • 🤖

    MCP SDK integration

    browserAuth().connect(client) runs the whole browser flow; the MCP SDK does discovery, DCR, PKCE, exchange and refresh.

  • ⚡

    Zero runtime dependencies

    The browser launcher is bundled and loaded lazily, only when it is used.

  • 🎯

    Small, typed API

    One function, one error class, and a two-method credential store.

Quick Start ​

ts
import { getAuthCode } from "oauth-callback";

const { code, redirectUri } = await getAuthCode(() => {
  const url = new URL("https://github.com/login/oauth/authorize");
  url.searchParams.set("client_id", CLIENT_ID);
  return url; // redirect_uri and state are appended
});

await exchangeCode({ code, redirectUri }); // your token request
ts
import { Client } from "@modelcontextprotocol/client";
import { browserAuth, fileStore } from "oauth-callback/mcp";
import { homedir } from "node:os";
import { join } from "node:path";

const auth = browserAuth({
  serverUrl: "https://mcp.notion.com/mcp",
  redirectUri: "http://127.0.0.1:8765/callback",
  clientName: "Acme CLI",
  store: fileStore(join(homedir(), ".config/acme/notion.json")),
});

const client = new Client({ name: "acme", version: "1.0.0" });
await auth.connect(client); // opens the browser if needed
bash
bun add oauth-callback
# or
npm install oauth-callback
npm versionnpm downloadsMIT License