Oh My Linear MCP

Ask your agent for list_issues and watch 30k+ tokens disappear into deeply nested metadata.

oh-my-linear exists to stop that.

It reads from Linear.app's local IndexedDB cache first, returns compact shapes fast, and only goes to official Linear MCP when it actually has to.

"Show me Frontend issues"

Official-only path: big payload, high token burn
oh-my-linear path: focused fields (identifier/title/priority/state/assignee/dueDate)

Same question. Smaller context bill.

How It Works

Linear desktop app (Electron) already syncs your workspace to local IndexedDB. oh-my-linear opens that cache and routes tools with one rule set:

1. Try refreshing local cache only when stale.
2. Read locally first.
3. Fallback to official only if local path is unsupported/unavailable.
4. Compose one visible tool surface at startup:
   • local read tools stay local
   • shared local read tools synchronize their runtime-visible descriptions to the official MCP wording for discoverability/search parity
   • official tools whose names do not collide with local read tools are discovered once and exposed as passthrough tools
   • read-name collisions stay owned by the local path

Routing Policy (0.6.6)

Read path:

• refresh_cache() is conditional:
  • refresh when TTL expired, or
  • refresh when local DB/blob mtime is newer than loaded cache
• refresh failure does not immediately force official fallback
  • stale local cache is still used when present
• official fallback happens when:
  • local cache is empty on cold start, or
  • handler raises LocalFallbackRequested (unsupported query/tool shape)

Write path:

• official passthrough tool names discovered at startup (e.g. create_issue, update_issue) -> official Linear MCP direct
• call_linear_tool_raw(name, args) remains as explicit raw passthrough

Install

Requirements:

• macOS
• Linear.app installed and opened at least once
• Node.js (npx) for default official stdio bridge

Project setup helper (writes/updates <project>/.mcp.json):

uvx oh-my-linear install --project /path/to/project --name oh-my-linear --client claude

Claude Code:

claude mcp add oh-my-linear -- uvx oh-my-linear

Codex:

codex mcp add oh-my-linear -- uvx oh-my-linear

Exposed Tool Surface

oh-my-linear exposes one composed MCP surface:

visible_tools(oh-my-linear)
  = local_read_tools
  + official_tools_except_local_read_name_collisions
  + call_linear_tool_raw

Startup discovery:

• oh-my-linear calls downstream official list_tools() once during startup
• shared local read tools keep local execution, but adopt the exact official description text at startup
• this keeps search/tool-selection wording consistent even when the call stays local
• local read tool names win on collisions such as list_issues
• the remaining official tools are registered as passthrough tools on oh-my-linear

Local-first reads:

list_issues, get_issue, list_teams, list_projects, get_team, get_project, list_users, get_user, list_issue_statuses, get_issue_status, list_comments, list_issue_labels, list_initiatives, get_initiative, list_cycles, list_documents, get_document, list_milestones, get_milestone, get_status_updates, list_project_updates

Official bridge:

• Official tools whose names do not collide with local read tools are discovered from Linear MCP at startup and re-exposed on oh-my-linear (same tool names/descriptions, excluding local read collisions)
• call_linear_tool_raw(name, args) remains as the raw fallback/escape hatch
• If startup discovery fails, local read tools still load and call_linear_tool_raw remains available, but mirrored official tools may be missing until restart and shared local descriptions fall back to their built-in wording

Migration Notes

Removed tool endpoints:

• list_official_tools
• reconnect_official
• refresh_cache
• get_cache_health
• reauth
• official_call_tool

Replacement:

• prefer composed official passthrough tools directly (e.g. create_issue, update_issue, ...)
• use call_linear_tool_raw(name, args) for explicit passthrough
• when downstream official Linear auth expires, reauthenticate by opening your client's /mcp flow and reconnecting the oh-my-linear server, then retry the original tool call

CLI entrypoints:

• primary: oh-my-linear
• compatibility aliases: oh-my-linearmcp, linear-mcp-fast
• default behavior (oh-my-linear): run MCP server (serve)
• helper command:
  • oh-my-linear install --project /path/to/project --name oh-my-linear --client claude

Configuration

Official transport:

• LINEAR_OFFICIAL_MCP_TRANSPORT (stdio default, or http)
• LINEAR_OFFICIAL_MCP_COMMAND (npx default)
• LINEAR_OFFICIAL_MCP_ARGS (-y mcp-remote https://mcp.linear.app/mcp default)
• LINEAR_OFFICIAL_MCP_ENV (JSON env for stdio child)
• LINEAR_OFFICIAL_MCP_CWD (working directory for stdio child)
• LINEAR_OFFICIAL_MCP_URL (https://mcp.linear.app/mcp default for http transport)
• LINEAR_OFFICIAL_MCP_HEADERS (JSON headers for http transport)

Local refresh policy:

• LINEAR_FAST_REFRESH_TTL_SECONDS (default 10)
• LINEAR_FAST_ACCOUNT_EMAILS (optional account scope filter)
• LINEAR_FAST_USER_ACCOUNT_IDS (optional account scope filter)

OAuth retry suppression:

• LINEAR_OFFICIAL_AUTH_RETRY_COOLDOWN_SECONDS (default 300)

Troubleshooting

Official Linear auth expired or consent changed:

1. Open your MCP client's /mcp flow.
2. Reconnect or reauthenticate the oh-my-linear server entry.
3. Retry the original tool call after the auth window completes.
4. If the client is still in cooldown, reconnect once more after auth so a fresh server instance clears the suppressed retry state.

OAuth page keeps opening:

1. Check official URL is not localhost by mistake.
2. Finish the login/consent flow, then reconnect oh-my-linear from /mcp.
3. Confirm auth session is valid.
4. Avoid tight retry loops from clients.
5. Keep cooldown enabled (LINEAR_OFFICIAL_AUTH_RETRY_COOLDOWN_SECONDS).

Local data seems stale:

1. Open Linear.app to force sync.
2. Lower LINEAR_FAST_REFRESH_TTL_SECONDS if you want more aggressive refresh.

npx: command not found:

• install Node.js, or switch to LINEAR_OFFICIAL_MCP_TRANSPORT=http.

License

MIT