# 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.

Writes are explicit and always go to official MCP through `official_call_tool`.

## Routing Policy (0.6.2)

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_call_tool(name, args)` -> official Linear MCP direct

## 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`):

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

Claude Code:

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

Codex:

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

## Exposed Tool Surface

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_call_tool(name, args)`

## Migration Notes

Removed tool endpoints:
- `list_official_tools`
- `reconnect_official`
- `refresh_cache`
- `get_cache_health`
- `reauth`

Replacement:
- use `official_call_tool(name, args)` for writes and official-only operations

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

OAuth page keeps opening:
1. Check official URL is not localhost by mistake.
2. Confirm auth session is valid.
3. Avoid tight retry loops from clients.
4. 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
