A TypeScript SDK for the Plane API, with an MCP server and a CLI built on top of it. Use it from code, from an AI agent, or from your terminal: all three share the same client.
Documentation: hoyasumii.github.io/plane (English and Português).
- SDK: a typed client for API v1 and the whole v2 surface (
client.v2, 90 resources).fieldsnarrows the return type at compile time, and fetched rows can be navigated to their children. - MCP server (
@hoyasumii/plane/mcp): stdio or Streamable HTTP. It has task tools that work with keys and names (ACME-130,"Todo","me") and generic tools that reach every v2 method. - CLI (
plane): every MCP tool as a subcommand, plusplane mcpto configure the server, run it in the background, start it at login and register it in Claude Code, Codex and OpenCode. - Works with Plane Cloud and self-hosted instances, including self-hosted 1.4.x, which has no API v2.
Requires Node.js 20 or later.
npm install @hoyasumii/plane
# or
pnpm add @hoyasumii/planeimport { PlaneClient } from "@hoyasumii/plane";
const client = new PlaneClient({ apiKey: "your-api-key" });
// Or against a self-hosted instance, with an OAuth access token:
const selfHosted = new PlaneClient({
baseUrl: "https://plane.example.com",
accessToken: "your-access-token",
});
// API v2: path ids are positional and come first, in URL order.
await client.v2.workspaces.projects.states.list("acme", "ENG");
// A fetched row carries its ids, so its children need none.
const eng = await client.v2.workspaces.projects.retrieve("acme", "ENG");
await eng.workItems.create({ name: "Fix login bug", state: "Todo", labels: ["bug"] });
// API v1: every workspace-scoped call takes the workspace slug first.
const projects = await client.projects.list("workspace-slug");Save your settings once, then register the MCP server in the clients on your machine:
npx plane mcp config # the API key, the instance URL, a default workspace
npx plane mcp install # registers plane-mcp in Claude Code, Codex and OpenCodeThe same tools work from the terminal:
npx plane whoami
npx plane list-my-issues
npx plane get-issue --key ACME-14| Topic | What it covers |
|---|---|
| Getting started | installation, the first calls, the three ways to use the package |
| API v2 | the flat path, loaded rows, field projection, bulk writes, pagination |
| API v1 | the v1 resources and their sub-resources |
| Authentication | API keys, access tokens and the OAuth client |
| MCP server | transports, every tool, configuration, programmatic use |
| CLI | tools as commands, plane mcp, Windows and WSL |
| API reference | every exported class, type and function, generated from the source |
| Contributing | building, testing, and how the v2 surface is kept honest |
The site's source is in website/: pnpm docs:dev previews it.
MIT. See LICENSE.
This project started from makeplane/plane-node-sdk and is developed independently. It is not affiliated with or endorsed by Plane Software, Inc. "Plane" is their trademark.