oh-my-linear 0.6.1

OhMyLinearMCP - unified Linear MCP (local-fast reads + official fallback/writes) on macOS

Oh My Linear MCP

oh-my-linear is a Linear MCP router:

• Reads: local IndexedDB first (Linear.app cache)
• Writes: official Linear MCP direct
• Local read unsupported/unavailable: official fallback

3-Rule Architecture

1. Every read call attempts cache refresh only when stale (TTL) or source mtime changed.
2. The router tries the local read handler first.
3. Official fallback happens only when local read handling is unsupported/unavailable or local cache is empty on cold start.

Writes are always explicit through official_call_tool, which calls official Linear MCP directly.

Install

Requirements:

• macOS with Linear.app installed and opened at least once
• Node.js (npx) when using default stdio transport

Install in Claude Code:

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

If you want to add official Linear MCP directly (reference):

claude mcp add --transport http linear-server https://mcp.linear.app/mcp

Routing Model

Exposed Tool Surface

Local-first read tools

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 passthrough tool

official_call_tool(name, args)

Use this for writes and any official-only tool. get_status_updates automatically falls back to official MCP for unsupported local filters/types.

Migration Notes (0.6.0)

Removed MCP tools:

• list_official_tools
• reconnect_official
• refresh_cache
• get_cache_health
• reauth

Replacement:

• Use official_call_tool(name, args) for official-only operations and writes.

CLI entrypoints:

• Primary: oh-my-linear
• Legacy aliases still available: oh-my-linearmcp, linear-mcp-fast

Configuration

Official transport:

• LINEAR_OFFICIAL_MCP_TRANSPORT: stdio (default) or http
• LINEAR_OFFICIAL_MCP_COMMAND: default npx
• LINEAR_OFFICIAL_MCP_ARGS: default -y mcp-remote https://mcp.linear.app/mcp
• LINEAR_OFFICIAL_MCP_ENV: JSON object for stdio child env
• LINEAR_OFFICIAL_MCP_CWD: working directory for stdio child
• LINEAR_OFFICIAL_MCP_URL: URL for http transport (default https://mcp.linear.app/mcp)
• LINEAR_OFFICIAL_MCP_HEADERS: JSON headers for http transport
• LINEAR_FAST_REFRESH_TTL_SECONDS: local refresh TTL seconds (default 10)

Auth retry suppression:

• LINEAR_OFFICIAL_AUTH_RETRY_COOLDOWN_SECONDS: seconds to suppress reconnect attempts after auth-like failures (default 300)

OAuth Popup Troubleshooting

If OAuth pages open repeatedly:

1. Verify you are not pointing official MCP to a local unstable endpoint.
   • Check LINEAR_OFFICIAL_MCP_URL
   • Default should be https://mcp.linear.app/mcp (not http://localhost:*)
2. Confirm the official MCP auth session is valid.
3. Avoid tight retry loops from clients while auth is failing.
   • This server suppresses repeated auth retries for the cooldown window (default 300s).

Known Behavior

• Local cache can be degraded while still serving some reads from previous cache.
• Official fallback occurs when the local read path is unsupported/unavailable for that call.