Linear MCP (multi-workspace, PAT auth)

linear-mcp

Personal API Key 認証を使用する、複数ワークスペース対応の Linear MCP サーバーです。mcp.linear.app/mcp にある公式の OAuth 専用 Linear MCP とそのまま置き換えられます。

これが必要な理由。 公式の Linear MCP は OAuth 専用で、インスタンスごとに単一のワークスペースしか扱えません。PAT 認証、永続的なトークン保存、複数ワークスペースへのルーティングにより、3 つの失敗要因を解消します。

1. MCP クライアントのセッション境界をまたぐと、OAuth フローは不安定になります。フローの途中でセッションが再開されると、認証状態が期限切れになります。
2. 一部の環境では localhost のコールバックが失敗し、脆弱な貼り付けによる受け渡しが必要になります。
3. ワークスペースごとに MCP インスタンスを用意すると、設定と OAuth の手順が二重になります。

このサーバーなら、どちらの問題も 1 つのエントリで解決できます。インストールは 1 回だけで、N 個のワークスペースに対応し、OAuth の手順はもう必要ありません。

インストール

PyPI から

pipx install adelaidasofia-linear-mcp

ソースから

git clone https://github.com/adelaidasofia/linear-mcp ~/.claude/linear-mcp
cd ~/.claude/linear-mcp
pip install -e .

Claude Desktop ワンクリックインストール

Releases から最新の .mcpb をダウンロードし、ダブルクリックします。

設定

1. https://linear.app/settings/account/security で、ワークスペースごとに Personal API Key を 1 つ生成します。キーを生成するワークスペースに、個別にログインしている必要があります。

2. ~/.claude/linear-mcp/admin.env を作成します（chmod 600）。

LINEAR_WORKSPACES=personal,work
LINEAR_PRIMARY_WORKSPACE=personal

LINEAR_PAT_PERSONAL=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
LINEAR_PAT_WORK=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

LINEAR_LABEL_PERSONAL=Personal
LINEAR_LABEL_WORK=Work

エイリアスは任意です。ルーティングに便利な名前を付けてください（acme,beta、team1,team2、home,client など）。

chmod 600 ~/.claude/linear-mcp/admin.env

3. Claude Code に登録します（すべてのプロジェクトで読み込まれるよう、ユーザースコープに設定します）。

claude mcp add -s user linear-mcp python3 -m linear_mcp.server

または、pipx でインストールする場合：

claude mcp add -s user linear-mcp linear-mcp

4. Claude Code を再起動します。ワークスペースごとに healthcheck が ok: true を返すことを確認してください。

基盤レイヤーでの強制チェック（v0.3）

Markdown のルールファイルやクライアント側のメモリに依存せず、イシューの品質を守る 3 つのサーバー側チェックです。WRITE パスのみに適用され、読み取りは制約されません。

レイヤー	動作	バイパス用環境変数
[source:] の先頭行チェック	save_issue / save_project は、description（またはプロジェクトの content）が [source: <canonical-key>] で始まらない CREATE 呼び出しを拒否します。UPDATE 呼び出し（id を指定）はチェックをスキップするため、既存データのバックフィルは引き続き実行できます。	LINEAR_MCP_SKIP_SOURCE_CHECK=1
冪等性チェック	CREATE の前に、サーバーは [source: <key>] を指定して searchIssues / searchProjects を実行し、重複の作成を拒否します。エラーには既存の識別子と UUID が表示されるため、呼び出し元は既存の項目を更新できます。	LINEAR_MCP_SKIP_IDEMPOTENCY=1
bulk_save_issues の auth_phrase	bulk_save_issues では、auth_phrase に {"go"、"yes do it"、"confirmed"、"execute"、"go cancel"、"go update"} のいずれかを指定する必要があります（大文字と小文字は区別されません）。大量変更を行う際の確認手順は明示的なままです。	（バイパス不可 — フレーズをオペレーターに提示してください）

正規キーの例：

• [source: 🍄 Mycelium AI/📝 Meeting Notes/2026-05-22 - sync.md]
• [source: ⚙️ Meta/Decisions/2026-05-23-merger-public-comms.md]
• [source: linear-kickoff:sweep-myc-p1]
• [source: ~/.claude/linear-mcp/BUILD_PROMPT_V03.md]

イシューからすばやく作業を開始

linear-exec は、Linear のイシューから実際の作業を開始するための最短ルートです。 イシューを特定し、ブロック関係を確認し、同じプロジェクト内の関連イシューを調べて明らかなスコープの重複がないかを確認します。可能な場合はリポジトリを推定し、標準の claude-dev-worktree ブランチを作成できます。

特定のイシューをドライランします。

linear-exec execute MYC-150 --workspace mycelium

事前チェックの内容を確認してから作業を開始します。

linear-exec execute MYC-150 --workspace mycelium --repo memory-runtime-pro --go

ワークスペース内で、ブロックされていない次の P1 イシューを探します。

linear-exec sweep mycelium p1
linear-exec sweep mycelium p1 --go --repo memory-runtime-pro

上流の blocks 関係が未完了の場合、--force を指定しない限りコマンドは実行を拒否します。--no-state-update と --no-worktree を指定すると、エージェントは事前チェックの必要な部分だけを利用できます。

ツール一覧（v0.3 — 57 個のツール + 3 個のプロンプト）

すべてのツールで workspace パラメーター（LINEAR_WORKSPACES に設定したエイリアス）を任意で指定できます。省略すると LINEAR_PRIMARY_WORKSPACE が使用されます。

メタ

ツール	用途
list_workspaces	設定済みのワークスペースとプライマリワークスペースを表示します
healthcheck	各 PAT を検証し、残りのレート制限枠を表示します

コアエンティティ

ツール	用途
list_teams / get_team	チーム（ワークフローの状態をインラインで含みます）
list_users / get_user	ユーザー（me は PAT の所有者に解決されます）
list_projects / get_project / save_project	プロジェクト（v0.3：save_project は content 内の [source:] を必須とし、CREATE 時の冪等性を保証します）
list_initiatives / get_initiative / save_initiative	イニシアチブ
list_issues / get_issue / save_issue / bulk_save_issues	課題（ID または ONDE-123。一括処理では issueBatchUpdate を使用します。v0.3：save_issue は [source:] を必須とし、CREATE 時の冪等性を保証します。bulk_save_issues には auth_phrase が必要です）
list_cycles	サイクル
list_milestones / get_milestone / save_milestone	プロジェクトのマイルストーン
list_issue_statuses / get_issue_status	ワークフローの状態
list_issue_labels / create_issue_label	ラベル
list_comments / save_comment	コメント
list_documents / get_document / save_document	ドキュメント
save_status_update	プロジェクトのステータス更新を投稿します

Webhook（v0.2）

ツール	用途
list_webhooks / get_webhook	サブスクリプションを確認します
create_webhook / update_webhook	サブスクリプションを管理します
delete_webhook	破壊的操作 — 下書き作成と確認が必要です

通知／受信トレイ（v0.2）

ツール	用途
list_notifications / get_notification	受信トレイを読み取ります
notifications_unread_count	優先事項の件数
mark_notification_read / mark_all_notifications_read	トリアージ
archive_notification	一括整理

添付ファイル（v0.2）

ツール	用途
list_attachments / get_attachment	課題ごとの読み取り
attachments_for_url	逆引き：この URL にリンクしている課題を確認します
link_url_to_issue	任意の URL を課題に添付します
delete_attachment	破壊的操作 — 下書き作成と確認が必要です

課題の関連（v0.2）

ツール	用途
list_issue_relations	ブロック／重複／関連のグラフ
create_issue_relation / delete_issue_relation	グラフを管理します

エージェントセッション（v0.2）

ツール	用途
list_agent_sessions / get_agent_session	Linear のファーストクラスなエージェント機能
create_agent_session_on_issue / create_agent_session_on_comment	エージェントセッションを開始します

検索（v0.2 — v0.1 の壊れた search_documentation を置き換えます）

ツール	用途
search_issues / search_documents / search_projects	エンティティタイプごとの全文検索
semantic_search	ワークスペース内の全エンティティを対象とするセマンティック検索

MCP プロンプト（v0.2）

プロンプトを表示する MCP クライアントでは、スラッシュコマンドとして利用できます。

• /triage-issue — 分類、ラベル付け、優先順位付け、担当者の割り当て、重複課題へのリンクを行う完全なトリアージ
• /project-status — 現在の Linear の状態から週次ステータス更新の下書きを作成します
• /inbox-sweep — 今日の通知を確認し、対応を提案して、処理済みの通知をアーカイブします

複数ワークスペースの利用

ワークスペースをインラインで切り替えます。

list_teams(workspace="work")
save_issue(workspace="personal", title="Ship", team_id="...")

workspace を指定しない場合は、プライマリワークスペースが使用されます。

認証

Linear の PAT では、ヘッダー Authorization: <key> を使用します（Bearer プレフィックスは不要です）。各 PAT は 1 つのワークスペースに紐づき、所有ユーザーが閲覧できるデータにのみアクセスできます。組織共通のトークンはありません。

レート制限：トークンごとに毎時 2500 リクエスト（2026-05-23 にライブ API で検証済み）。サーバーは Linear の Retry-After ヘッダーを 429 時にそのまま渡し、残りの利用枠を healthcheck で表示します。

安全性

読み取りツールと通常の書き込み（課題、コメント、ラベル、ステータス更新の作成・更新）はそのまま実行されます。破壊的操作（delete_webhook、delete_attachment）では、下書き＋確認のパターンを使用します。最初の呼び出しで変更をステージングし、draft_id と実行内容のプレビューを返します。2 回目の呼び出し（confirm_draft_id を指定）で変更を確定します。下書きの有効期限は 1 時間です（LINEAR_MCP_DRAFT_TTL_SECONDS で変更できます）。

すべてのツール呼び出しは、~/.claude/linear-mcp/audit.log に JSONL 形式の行を 1 行追加します（LINEAR_MCP_AUDIT_LOG_PATH で保存先を変更でき、LINEAR_MCP_AUDIT_LOG=false で無効にできます）。監査記録からトークンは除外されます。

healthcheck はワークスペースごとに、各 PAT の残りのレート制限枠（X-RateLimit-Requests-Remaining と X-Complexity-Remaining）を表示するため、エージェントは別途、可観測性のための呼び出しを行わずにリクエスト頻度を調整できます。

関連する MCP

• adelaidasofia/slack-mcp — 下書き＋確認に対応したマルチワークスペース Slack
• adelaidasofia/whatsapp-mcp — whatsmeow 経由の WhatsApp と vault へのエクスポート
• adelaidasofia/imessage-mcp — iMessage chat.db と vault へのエクスポート
• adelaidasofia/github-mcp — GitHub の PR／課題／リリース

ライセンス

MIT。

---

Adelaida Diaz-Roa が開発しました。完全版またはチーム版のインストールについては、diazroa.com をご覧ください。