granola-api

TypeScript client for the Granola MCP API — OAuth, meeting data, and transcript access.

• Zero runtime dependencies (Node.js stdlib only)
• OAuth 2.0 with PKCE
• Automatic token refresh with pluggable storage
• MCP session management and rate-limit tracking
• Dual ESM/CommonJS builds

Install

npm install granola-api
# or
pnpm add granola-api

Quick Start

import {
  GranolaClient,
  registerClient,
  generatePKCE,
  generateState,
  buildAuthorizationUrl,
  exchangeCode,
} from 'granola-api';

// 1. Register an OAuth client
const { clientId } = await registerClient('My App', 'http://localhost:3000/callback');

// 2. Generate PKCE challenge and start OAuth flow
const { codeVerifier, codeChallenge } = await generatePKCE();
const state = generateState();
const authUrl = buildAuthorizationUrl(clientId, 'http://localhost:3000/callback', state, codeChallenge);
// Redirect user to authUrl...

// 3. Exchange the authorization code for tokens
const tokens = await exchangeCode(clientId, 'http://localhost:3000/callback', code, codeVerifier);

// 4. Use the client
const client = new GranolaClient();
const meetings = await client.listMeetings(tokens.accessToken, '2025-01-01', '2025-01-31');

API

GranolaClient

const client = new GranolaClient(options?: GranolaClientOptions);

| Option | Type | Default | Description | |--------|------|---------|-------------| | clientName | string | 'Granola API Client' | Name sent during MCP initialization | | clientVersion | string | '1.0.0' | Version sent during MCP initialization | | tokenStore | TokenStore | — | Pluggable token persistence for automatic refresh | | requestTracker | RequestTracker | — | Optional callback for request metrics |

Methods

listMeetings(accessToken, startDate, endDate) — List recent meetings within a date range.

getMeetings(accessToken, meetingIds) — Get detailed meeting information by IDs.

getMeetingTranscript(accessToken, meetingId) — Get the full transcript for a meeting.

getValidAccessToken(userId) — Get a valid access token, refreshing if needed. Requires a TokenStore.

getCurrentRPM() — Get the current in-process requests-per-minute count.

callMCP(accessToken, method, params) — Low-level MCP tool call for direct protocol access.

OAuth Functions

| Function | Description | |----------|-------------| | registerClient(name, redirectUri) | Register a new OAuth client with Granola | | generatePKCE() | Generate a PKCE code verifier and challenge | | generateState() | Generate a random state token | | buildAuthorizationUrl(clientId, redirectUri, state, codeChallenge) | Build the OAuth authorization URL | | exchangeCode(clientId, redirectUri, code, codeVerifier) | Exchange an authorization code for tokens | | refreshAccessToken(clientId, refreshToken) | Refresh an expired access token |

Parsing Functions

| Function | Description | |----------|-------------| | parseMeetingList(raw) | Extract meeting IDs and titles from a list response | | parseMeetingListFull(raw) | Full parsing with attendees, times, and notes | | parseMeetingDetails(raw) | Parse meeting details including transcript |

Types

interface GranolaTokens {
  accessToken: string;
  clientId: string;
  expiresAt: number;       // Unix timestamp (ms)
  refreshToken: string;
}

interface GranolaMeeting {
  id: string;
  title: string;
  startTime: string;
  endTime?: string;
  attendees?: GranolaAttendee[];
}

interface GranolaPayload {
  id: string;
  title: string;
  transcript: string;
  enhanced_notes: string;
  my_notes: string;
  attendees: GranolaAttendee[];
  creator_name: string;
  creator_email: string;
  calendar_event_ID: string;
  calendar_event_title: string;
  calendar_event_time: string;
  link: string;
}

interface TokenStore {
  getTokens(userId: string): Promise<GranolaTokens | null>;
  storeTokens(userId: string, tokens: GranolaTokens): Promise<void>;
}

interface RequestTracker {
  trackRequest(toolName: string, status: number, durationMs: number): void | Promise<void>;
}

Token Storage

Implement the TokenStore interface to persist tokens in your backend:

import { GranolaClient, type TokenStore } from 'granola-api';

const store: TokenStore = {
  async getTokens(userId) {
    return db.granolaTokens.findUnique({ where: { userId } });
  },
  async storeTokens(userId, tokens) {
    await db.granolaTokens.upsert({ where: { userId }, create: { userId, ...tokens }, update: tokens });
  },
};

const client = new GranolaClient({ tokenStore: store });
const accessToken = await client.getValidAccessToken('user-123');

Tokens are refreshed automatically when they expire within 5 minutes.

Development

pnpm install
pnpm dev          # Watch mode
pnpm build        # Production build
pnpm typecheck    # Type check without emitting

License

MIT