# 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 refreshes the local cache once.
2. The router tries the local read handler first.
3. If local read handling is unavailable or unsupported, the same call falls back to official Linear MCP.

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:

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

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

```bash
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

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.
