openbird

library3.6.0jsnpmunverified

Feishu (Lark) toolbox for AI Agents, providing 77 MCP tools via stdio and WebSocket event relay. Current stable version: 3.6.0. Release cadence: rolling releases via npm. Key differentiators: uses browser cookie authentication (no API token needed), runs locally, and offers two modes — MCP mode for AI client integration (Claude Desktop, Cursor) and Relay mode for webhook event forwarding. Supports 20+ event types, semantic deduplication, and exponential backoff retry. Requires Node.js >=20 and a Feishu browser cookie. Migration from v2 to v3 splits implicit webhook behavior into explicit commands.

messaging ai-ml

npm install openbird

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENBIRD

openbird

messagingjavascriptv3.6.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

(npx usage)

✓ npx -y openbird mcp

✗ Running without npx (require global install) or missing -y flag

OpenBird is designed to be run via npx. No install required.

(Relay mode)

✓ npx -y openbird relay http://localhost:3000/webhook

✗ Using OPENBIRD_WEBHOOK_URL env variable (v2 pattern) without the explicit command

v3 removed implicit webhook from MCP mode. Must use explicit 'relay' command.

createServer (from openbird-webhook-node)

✓ import { createServer } from 'openbird-webhook-node'

✗ require('openbird-webhook-node') without destructuring; import default

Separate package for receiving events; not part of OpenBird itself. ESM only.

Shows how to configure OpenBird in MCP client (Claude Desktop) and run both modes.

// Ensure OPENBIRD_COOKIE env var is set with your Feishu browser cookie // For Claude Desktop configuration (mcpServers): { "mcpServers": { "openbird": { "command": "npx", "args": ["-y", "openbird", "mcp"], "env": { "OPENBIRD_COOKIE": "your_cookie_here" } } } } // To run MCP mode directly: // OPENBIRD_COOKIE="your_cookie_here" npx openbird mcp // To run Relay mode: // OPENBIRD_COOKIE="your_cookie_here" npx openbird relay http://localhost:3000/webhook

Debug

Known issues

breakingv3 removes implicit webhook from MCP mode. The OPENBIRD_WEBHOOK_URL env variable no longer triggers webhook forwarding.

fix

Use explicit 'npx openbird relay <webhook-url>' command to start relay mode. See README migration section.

affects: >=3.0.0

gotchaOPENBIRD_COOKIE must contain the full Cookie header string from a feishu.cn request, including all tokens. A partial cookie will result in authentication failure.

fix

Copy the entire Cookie header (not just a single token) from DevTools network tab. Example: 'session=abc; ...'

affects: >=1.0.0

gotchaNode.js version must be >=20.0.0. Older versions will fail to run.

fix

Upgrade Node.js to version 20 or later.

affects: >=1.0.0

deprecatedRunning 'npx openbird' without a subcommand (mcp/relay) may be deprecated in future versions. Current behavior is not defined.

fix

Always specify either 'mcp' or 'relay' as the first argument.

affects: >=3.0.0

gotchaRelay mode does not start MCP server. To run both, you need two separate processes.

fix

Run two terminals: one with 'npx openbird mcp' and another with 'npx openbird relay <url>'.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cookie not found or invalid. Please set OPENBIRD_COOKIE environment variable.

OPENBIRD_COOKIE is missing or contains an invalid cookie string.

fix

Set OPENBIRD_COOKIE to the full Cookie header from a feishu.cn request. Use correct format: key=value; key2=value2

Error: Command not recognized. Usage: openbird <mcp|relay>

Running 'npx openbird' without a subcommand or with an invalid subcommand.

fix

Use either 'npx openbird mcp' or 'npx openbird relay <webhook-url>'.

Error: Failed to connect to WebSocket: Connection refused

Feishu WebSocket endpoint unreachable (network issue or cookie expired).

fix

Ensure network connectivity to feishu.cn and cookie is valid (not expired). Renew cookie if needed.

Error: Node.js version must be >= 20.0.0

Running OpenBird on an older Node.js version.

fix

Upgrade Node.js to version 20 or later (e.g., nvm install 20).

TypeError: createServer is not a function (from openbird-webhook-node)

Incorrect import: using default import instead of named import.

fix

Use: import { createServer } from 'openbird-webhook-node'

Upgrade

Version history

3.6.0latest on npm

Audit

Dependencies

openbird-webhook-nodeoptionalOptional server library for receiving OpenBird Relay events in Node.js

Agent activity

18 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/ztxtxwd/openbird ↗

packageopenbird ↗

homepagehttps://github.com/ztxtxwd/openbird#readme ↗