Linear MCP

Multi-workspace MCP server for Linear, built with Bun/TypeScript and raw GraphQL.

It covers issues, projects, initiatives, documents, comments, views, templates, notifications, attachments, and files, with complete comment readback, authenticated private-file handling, validated visual metadata, and MCP tool annotations. See CAPABILITIES.md for the generated tool reference.

• Active local source: /Users/jonas/.agents/mcp/servers/linear

• Workspaces: interlink-group and personal

• Auth: LINEAR_INTERLINK_GROUP_TOKEN and LINEAR_PERSONAL_TOKEN

• Generated tool reference: CAPABILITIES.md

Agent Usage

Fresh sessions should use one source-of-truth chain:

1. Runtime MCP tool discovery for callable names, descriptions, and schemas.

2. CAPABILITIES.md for the generated human-readable index, examples, and tool-choice guidance.

3. /Users/jonas/.agents/skills/linear/SKILL.md for workspace routing and operating policy.

4. Live MCP reads for IDs and current Linear workspace state.

Do not copy tool tables into skills, README sections, or Linear comments. If tool behavior changes, update the implementing ToolDef metadata/examples under tools/, regenerate CAPABILITIES.md, and keep the skill focused on policy rather than a second reference.

Related MCP server: MCP Linear.app Server

Setup

bun install
cp .env.example .env
bun run start

The local production launch path uses /Users/jonas/.agents/mcp/wrappers/linear.sh, which loads tokens through the neutral MCP wrapper layer. The smoke scripts in package.json assume that local control-plane layout.

Both workspaces use Jonas's user credentials, so Linear comments and documents appear as Jonas.

Scripts

bun run prepare:repo
bun run verify
bun run smoke:tools
bun run smoke:tools:local
bun run smoke:views
bun run smoke:comments -- --workspace personal --confirm-live-write personal
bun run smoke:files -- --workspace interlink-group --confirm-live-write interlink-group

Use bun run prepare:repo before committing source changes. It refreshes the generated capabilities reference, then runs the normal local verification path. GitHub CI runs docs, build, and credential-free tool discovery; live Linear calls still depend on local credentials and the local MCP wrapper layout.

Live-write tests are opt-in and have no workspace default. Each run must pass an explicit personal or interlink-group target and repeat that exact value in --confirm-live-write. These narrow tests use unique fixture names, delete their current-run artifacts in finally, and exit nonzero if cleanup fails. Normal CI and verification remain unit/read-only by default.

Layout

index.ts
workspaces.ts
client.ts
tools/
  registry.ts
  issues.ts
  projects.ts
  initiatives.ts
  views.ts
  templates.ts
  files.ts
  attachments.ts
  ...