spec-workflow-mcpは、AIコーディングエージェントに「要件 → 設計 → タスク → 実装」の順序と、各段階で人の承認を待つことを指示するMCP（Model Context Protocol）サーバーです。作者はPimzino氏で、npmパッケージ名は@pimzino/spec-workflow-mcp、ライセンスはGPL-3.0です。2026年10月19日時点でnpmの最新版は2.2.5（2026年3月2日公開）で、GitHubのスターは約4,300です。
この記事では、npmから2.2.5を入れて手元のmacOS（Node.js v26.5.0）で起動し、ツール一覧・起動オプション・空のキャッシュからの取得時間・承認要求の書き込み先を確かめた結果をもとに、導入からクライアント別の設定、社内導入前に確認すべき点までを順に説明します。
まとめ
- spec-workflow-mcpは専用IDEではなく、Claude Code・Cursor・Codexなど今使っているエージェントに後付けするMCPサーバーです。成果物はプロジェクト直下の
.spec-workflow/にMarkdownで残ります。 - 導入はnpxだけですが、検証環境でのインストール容量は依存を含めて355MBで、空のnpmキャッシュからヘルプ表示コマンドが終了するまで実測で71秒かかりました。起動タイムアウトが既定10秒のCodexでは、設定で待ち時間を延ばすか、先に一度パッケージを取得しておきます。
- 配布版2.2.5が公開するツールは5つです。公式ドキュメントのツール一覧（13個）や、古い記事にある
--AutoStartDashboard・--configは現行版では使えず、後者2つは「Unknown option」で起動に失敗します。 - GitHubのmainは2.2.7まで進んでいますが、2.2.6と2.2.7はnpmに公開されていません。2.2.7で直された承認要求の経路外書き込み（Issue #220）は、配布版2.2.5で再現しました。
- 作者は2026年7月3日からREADMEで開発の一時休止を告知しています。チームの標準プロセスに組み込むなら、版の固定と実行環境の隔離を前提にしてください。
spec-workflow-mcpの仕組みと3つの提供物
spec-workflow-mcpは独自のエディタや実行環境を持ちません。コードを書くのは接続したAIエージェントのままで、そこに「順序」と「承認」を差し込みます。サーバーは承認状態を管理し、承認前に次の段階へ進まないようエージェントに指示します。ただし、ファイルを書くのはエージェント自身で、その編集をサーバーが技術的に禁止する仕組みではありません。手法としての仕様駆動開発の背景は仕様駆動開発（SDD）とは？従来手法との違いとSpec Kitで試す手順【2026年10月】で扱っているため、ここではツールの構成に絞ります。
- MCPサーバー本体：エージェントに手順と承認の状態を返します。npxでプロジェクトごとに起動します。
- Webダッシュボード：仕様書・タスク・承認待ちをブラウザで確認し、承認や差し戻しをする画面です。サーバーとは別プロセスで、1つ起動すれば全プロジェクトが同じ画面に並びます。
- VSCode拡張：
Pimzino.spec-workflow-mcp。ダッシュボードと同じ操作をサイドバーで行えます。Marketplaceの公開版は1.1.7（2026年1月28日）です。
サーバーを一度起動すると、プロジェクト直下に次のディレクトリが作られます（2.2.5で実際に生成されたもの）。要件・設計・タスクはspecs/、製品・技術・構造の方針を書くステアリング文書はsteering/に入り、テンプレートはtemplates/に6種類（requirements・design・tasks・product・tech・structure）が置かれます。すべてMarkdownなので、そのままGitで管理できます。
.spec-workflow/
├── approvals/ 承認要求のJSON
├── archive/
├── specs/ 仕様ごとの requirements.md / design.md / tasks.md
├── steering/ product.md / tech.md / structure.md
├── templates/ 同梱テンプレート
└── user-templates/ 独自テンプレートの置き場ダッシュボードの表示言語は日本語を含む11言語です。ツールの応答はJSONではなく、トークン消費を抑えるTOON形式で返ります（2.0.3で変更）。
インストールとダッシュボードの起動
インストール作業はありません。npxが使えるNode.js環境があれば動きます。2.2.5のpackage.jsonにはNode.jsのバージョン要件（engines）が書かれていないため、接続するエージェント側が求める版に合わせておきます。
npxでの起動と初回パッケージ取得の待ち時間
サーバーは対象プロジェクトのパスを渡して起動します。ふだんはエージェントのMCP設定に書いておき、エージェントが自動で起動します。
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1注意したいのは初回の待ち時間です。ダッシュボードのフロントエンド（React・Mermaid・エディタ部品など）まで依存に含むため、2.2.5を入れたnode_modulesは355MB・直下のパッケージ457個になりました。npmのキャッシュを空にした状態でnpx -y @pimzino/[email protected] --helpを実行すると71.4秒、2回目は4.5秒でした（回線速度で変わります）。エージェントが初回のパッケージ取得を待ちきれずにMCPサーバーを切り捨てると、設定は正しいのにツールが一覧に出てきません。導入直後に、設定と同じ版指定でnpx -y @pimzino/spec-workflow-mcp@latest --helpを一度実行しておくと、サーバーを起動し続けずにパッケージの取得とヘルプ表示までを確認できます。
ダッシュボードの起動とポート5000
Claude CodeやCodexなどCLIのエージェントから使う場合、承認操作のためにダッシュボードが必要です。別のターミナルで起動します。
npx -y @pimzino/spec-workflow-mcp@latest --dashboard既定のポートは5000で、http://localhost:5000で開きます。2.2.5の--helpに載っている起動オプションは次の5つだけです。
--dashboard：ダッシュボードだけを起動します（MCPサーバーは起動しません）。--port <番号>：1024〜65535で指定します。5000が使えないときだけ変えます。--no-open：起動時にブラウザを開きません。--no-shared-worktree-specs：gitワークツリーごとに.spec-workflow/を持たせます。--help：使い方を表示します。
ワークツリーとホームディレクトリの保存先
gitワークツリーで作業している場合、仕様は既定でメインリポジトリ側の.spec-workflow/に保存され、ワークツリー間で共有されます。保存先を指定したいときは環境変数SPEC_WORKFLOW_SHARED_ROOTを使います。
プロジェクト一覧などのグローバルな状態は~/.spec-workflow-mcpに書かれます。Codexをsandbox_mode = "workspace-write"で動かすときのようにホームディレクトリが書き込めない環境では、SPEC_WORKFLOW_HOMEで書き込める場所へ移します。
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace名前の似た別パッケージとの見分け方
パッケージ名のスコープを落とすと別の製品が入ります。npmのspec-workflow-mcp（スコープなし）はkingkongshot氏のspecs-workflow-mcp（MIT・1.0.8・2025年8月11日以降更新なし）で、ダッシュボードも承認画面もありません。検索結果のMCPディレクトリにもこちらが「Spec Workflow MCP」として載っているため、設定に書く名前は必ず@pimzino/spec-workflow-mcpにしてください。
同じ作者の前身として@pimzino/claude-code-spec-workflow（1.5.9・2025年9月7日が最終）もあります。Claude Code専用のスラッシュコマンド集で、READMEには開発の軸をMCP版へ移したと明記されています。これから導入するならMCP版を選びます。
Claude Code・Cursor・Codexでの設定手順
どのクライアントも、MCPサーバーの起動コマンドとしてnpxとプロジェクトのパスを登録する点は同じです。違うのは設定を書く場所と書式です。
Claude Code：claude mcp addとプラグインの2通り
コマンドで登録する場合は、区切りの--をサーバー名の直後に置き、その後ろに起動コマンドをまとめて書きます。
claude mcp add -s project spec-workflow -- npx -y @pimzino/spec-workflow-mcp@latest /path/to/projectClaude Code 2.1.302でこの形を実行すると、.mcp.jsonのargsは["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/project"]になりました。READMEの例（claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path）でも登録はできますが、npmの確認を省く-yが入りません。-s projectを付けるとリポジトリの.mcp.jsonに書かれ、チームで設定を共有できます。
もう1つはプラグインとして入れる方法です。リポジトリに.claude-plugin/marketplace.jsonがあり、Claude Codeのプラグイン手順どおりにマーケットプレイスを追加してからインストールします。
/plugin marketplace add Pimzino/spec-workflow-mcp
/plugin install spec-workflow-mcp@spec-workflow-mcp-marketplaceプラグインは2種類（spec-workflow-mcpとspec-workflow-mcp-with-dashboard）登録されていますが、2つの.mcp.jsonの中身は同じで、どちらもnpx -y @pimzino/spec-workflow-mcp@latest .を起動するだけです。名前に反してダッシュボードは自動で立ち上がらないため、別途--dashboardで起動します。プラグイン側の版表記は2.2.6ですが、実際に動くのはnpmの@latest＝2.2.5です。プラグインとmarketplace.jsonの仕組みはClaude Codeプラグインの作り方と社内配布｜marketplace.json・管理設定【2026年9月版】で解説しています。
Cursor：.cursor/mcp.jsonの設定
Cursorの設定先はCursorの公式ドキュメントのとおり、プロジェクト単位なら.cursor/mcp.json、全プロジェクト共通なら~/.cursor/mcp.jsonです。spec-workflow-mcpのREADMEはsettings.jsonと案内していますが、そこに書いても読まれません。
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/project"]
}
}
}同じmcpServersの書式は、Claude Desktop（claude_desktop_config.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）、Cline、Continue、Augment Codeでも使えます。ContinueでこのJSON形式を使う場合は、プロジェクトの.continue/mcpServers/mcp.jsonに保存します。OpenCodeはopencode.jsonのmcpに、type: "local"とコマンド配列で書きます。
Codex：config.tomlと起動タイムアウト
Codexは~/.codex/config.tomlにTOMLで書きます。CodexのMCPドキュメントによると、MCPサーバーの起動タイムアウトstartup_timeout_secの既定は10秒です。前述のとおり空のキャッシュからはヘルプ表示だけで71秒かかったため、キャッシュを作る前に使うならタイムアウトを延ばしておきます。
[mcp_servers.spec-workflow]
command = "npx"
args = ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/project"]
startup_timeout_sec = 120MCPの仕組みそのものから確認したい場合はMCP（Model Context Protocol）とは？AIと外部ツールをつなぐ標準規格の仕組みをわかりやすく解説を参照してください。
配布版2.2.5で使えるツール5つと文書作成の流れ
設定が済んだら、エージェントに「ユーザー認証の仕様を作って」のように頼むところから始まります。エージェントは要件（requirements.md）を書いて承認を求め、承認されたら設計（design.md）、次にタスク（tasks.md）と進み、最後にタスクを1つずつ実装します。仕様の名前はkebab-caseで付けます。
2.2.5に接続してツール一覧を取得すると、返ってきたのは次の5つでした。
| ツール名 | 役割 |
|---|---|
| spec-workflow-guide | 全体の手順書を返す（最初に呼ぶ） |
| steering-guide | ステアリング文書の作り方を返す |
| spec-status | 仕様とタスクの進捗を返す |
| approvals | 承認の要求・状態確認・削除 |
| log-implementation | 実装内容のログを記録する |
リポジトリのdocs/TOOLS-REFERENCE.mdにはcreate-spec-docやmanage-tasksなど13個のツールが説明されたままですが、これは古い構成の記述です。CHANGELOGの1.0.0（2025年9月13日）以降、文書はツールで作るのではなく、エージェントがテンプレートを読んで.spec-workflow/specs/<仕様名>/requirements.mdなどを直接書き、そのパスをapprovalsに渡す方式に変わりました。2.2.5の同梱プロンプトにはまだcreate-spec-doc（2か所）とget-template-context（1か所）の名前が残っており、エージェントがこれに引きずられて存在しないツールを呼ぶことがあります。その場合は設定ミスを疑う前に「テンプレートを直接読んでファイルを書いて」と指示すると進みます。
tasks.mdの進捗はチェックボックスで管理します。[ ]が未着手、[-]が作業中、[x]が完了です。完了にする前にlog-implementationで実装ログを残す手順になっており、ダッシュボードではこのログを検索できます。GitHubのmainには4つ目の状態として「ブロック中」[~]が入っていますが、これは未公開の2.2.7の機能で、npm版では使えません。
承認フローとダッシュボードの操作
承認はapprovalsツールの3つの操作で回ります。エージェントがaction: requestで承認を要求すると、ダッシュボードかVSCode拡張に承認待ちとして表示されます。エージェントはaction: statusで状態を問い合わせ、承認されたら次の段階へ進みます。差し戻しのコメントを付ければ、エージェントは文書を直して再度承認を求めます。承認済み・却下・修正要求の状態になった要求はaction: deleteで削除できますが、承認待ちの要求は削除できません。
2.2.5で承認を要求すると、応答には「BLOCKING – Dashboard approval required」「VERBAL APPROVAL NOT ACCEPTED」という指示が含まれていました。チャットで「OK」と返しても承認にはならず、ダッシュボードでの操作が必要という設計です。日本語表示での状態は「承認済み」「保留中」「修正が必要」「却下」で、ステアリング文書には「未作成」のバッジが付きます。
古い解説記事の設定で起動しない3つのケース
spec-workflow-mcpは2025年8月の公開から半年ほどで仕様が大きく変わり、当時の解説記事の設定をそのまま写すと動きません。2.2.5で確かめた失敗は次の3つです。
--AutoStartDashboardを付けている：MCPサーバーと同時にダッシュボードを起動するフラグでしたが、2.0.2（2025年11月6日）で削除されました。2.2.5に渡すと「Error: Unknown option: –AutoStartDashboard」と出て終了コード1で止まり、MCPサーバー自体が起動しません。args から外し、ダッシュボードは--dashboardで別に起動します。--configや.spec-workflow/config.tomlで設定している：config.tomlの対応も2.0.2で削除されています。--configも同じく「Unknown option」で起動に失敗します。リポジトリのdocs/CONFIGURATION.mdはまだconfig.tomlを案内しているので、設定は起動引数と環境変数で行ってください。- ポートが毎回変わる前提で書いている：一時ポートの対応も2.0.2で外れ、指定が無ければ5000で待ち受けます。
どの場合もエージェント側には「ツールが出てこない」としか見えないことが多いため、まずターミナルで同じ引数を付けて起動し、エラーが出ないかを確かめるのが早道です。
配布版2.2.5に残る未修正の問題と社内導入の確認事項
社内で使う前に、npm配布版とGitHubのソースの違いを確認してください。修正版の保守もMCPサーバー自体の隔離もできないチームは、未修正の2.2.5を標準プロセスに採用すべきではありません。
npm版とGitHub mainの版のずれ
2026年10月19日時点で、mainのpackage.jsonは2.2.7ですが、npmの最新は2.2.5のままです。2.2.6と2.2.7はCHANGELOGに記載があるだけで、配布されていません。
| 版 | CHANGELOGの日付 | 主な変更 | npm公開 |
|---|---|---|---|
| 2.2.4 | 2026-03-02 | filePathの任意ファイル読み取りを修正 | なし（2.2.5に統合） |
| 2.2.5 | 2026-03-02 | Fastify v5へ更新 | あり（現行の最新） |
| 2.2.6 | 2026-03-07 | 実装ログを完了前に必須化する指示の強化 | なし |
| 2.2.7 | 2026-05-04 | categoryNameの経路外書き込み修正・ブロック中状態 | なし |
2.2.4の修正（Issue #201）は、承認要求のfilePathに絶対パスや..を渡すとプロジェクト外のファイルを読み出せた問題で、2.2.5に含まれています。社内に2.2.3以前が残っていれば、それだけで更新の理由になります。
承認要求のcategoryNameで経路外に書き込める問題を2.2.5で再現
2.2.7で直されたIssue #220は、approvalsツールのcategoryNameを検証せずにディレクトリ名として使っていた問題です。2.2.5のMCPサーバーにクライアントから接続し、categoryNameに../../../swm_outsideを渡して承認を要求したところ、「Approval request created successfully」が返り、承認要求のJSONがプロジェクトの外（/tmp/swm_outside/）に作られました。filePath側には2.2.4で検査が入っていますが、categoryName側は配布版では素通りです。比較のためmain（2026年7月3日のコミット・2.2.7）をソースからビルドして同じ要求を送ると、「Security error: categoryName must be a simple name without path traversal or directory separators」で拒否され、プロジェクトの外には何も作られませんでした。
このツールを呼ぶのは人ではなくAIエージェントです。読み込んだIssueやWebページに仕込まれた指示でエージェントが操られると、細工した値で呼ばれる経路があり得ます。書き込まれるのは承認要求のJSONで、内容もタイトルやパスに限られますが、任意の場所にディレクトリとファイルを作れること自体が問題です。エージェントを外部の入力で操る攻撃の具体例はAgentjackingとは？偽のSentryエラーでAIコーディングエージェントを乗っ取る攻撃と防御で解説しています。
対策は次のどちらかです。1つは修正済みのmainをソースからビルドして使う方法で、手順はクローンしてnpm ciとnpm run buildを実行し、MCP設定のコマンドをnode /path/to/spec-workflow-mcp/dist/index.js /path/to/projectに置き換えるだけです。もう1つは2.2.5を使い続けたまま、MCPサーバー自体をコンテナなどで隔離し、ホスト側の書き込み可能なマウント先を対象プロジェクトに限定する方法です。Claude Codeの組み込みサンドボックスは通常のMCPサーバープロセスには適用されないため、その有効化だけではこの対策になりません。Claude Codeの権限ルールとサンドボックスがそれぞれ何を対象にするかはClaude Codeのセキュリティ設定｜権限ルール・サンドボックス・管理設定で守る実装手順で整理しています。
なお、2.2.7のCHANGELOGに並ぶ依存ライブラリの脆弱性修正（simple-gitのCVE-2026-28292、FastifyのCVE-2026-33806など）は、2.2.5の依存が^3.28.0のような範囲指定のため、新しくインストールすれば修正版が入ります。2026年10月19日に入れた2.2.5では、simple-gitが3.36.0、fastifyが5.12.7に解決されていました。古い環境ではnpm ls simple-git fastifyで解決済みの版を確認してください。
ダッシュボードの公開範囲
ダッシュボードは2.2.5のコード上、既定で127.0.0.1に待ち受け、それ以外のアドレスにバインドするには明示的な許可が要ります。レート制限はクライアントごとに1分120リクエストです。READMEのSecurity節が示すとおり、HTTPSとユーザー認証は実装されていません。チームで共有するなら、ダッシュボードはローカルに置いたままnginxなどのリバースプロキシでTLSと認証を受け持たせ、アクセス元もファイアウォールで絞ります。
GPL-3.0と開発休止の告知
ライセンスはGPL-3.0です。開発支援ツールとして起動して使うだけなら自社製品のライセンスには及びませんが、改変して社外へ配布する場合は条件が変わります。フォークして社内向けに手を入れるなら、先に法務の確認を通してください。
開発の継続性も判断材料です。READMEの冒頭には2026年7月3日のコミットで「個人的な事情でしばらく離れる」という告知が入り、それ以降mainへの変更はありません。npmの公開も3月2日で止まっています。単独の作者が作るツールを標準プロセスに組み込むなら、版を@2.2.5のように固定し、@latestで予告なく変わらないようにしておくのが安全です。AIエージェントの業務組み込みを設計から相談したい場合は、AIエージェント開発の支援もご覧ください。
Kiro・Spec Kit・cc-sddとの形態の違い
ここで比較する4製品では、spec-workflow-mcpが「今のエージェントに後付けするMCPサーバー」という形を取ります。
| ツール | 形態 | 承認画面 |
|---|---|---|
| spec-workflow-mcp | MCPサーバー | あり（ダッシュボード） |
| Kiro | AWS製のAI IDE・CLIほか | IDE内で段階ごとに確認 |
| Spec Kit | GitHub製のCLIとテンプレート | なし |
| cc-sdd | エージェントへのスキル配布 | なし |
Kiro IDEはエディタごと乗り換える選択肢ですが、Kiro CLIは既存のエディタと併用できます（Kiroとは？AWS製の仕様駆動AI IDEの特徴・料金・使い方を解説【2026年版】）。Spec Kitはspecify CLIでテンプレートとスラッシュコマンドを配置する方式で、承認の画面は持ちません（Spec Kit（GitHub）とは？仕様駆動開発の使い方・インストール・コマンドを徹底解説）。承認を画面で握りたい、エージェントがメンバーごとに違う、という条件ならspec-workflow-mcp、軽さを取るならSpec Kitやcc-sddが向きます。OpenSpecを含めた選び分けは仕様駆動開発ツール比較｜Spec Kit・Kiro・cc-sdd・OpenSpecの違いと選び方【2026年10月】とOpenSpecとは？使い方・インストール・/opsxコマンドをv1.14で解説にまとめています。
よくある質問
spec-workflow-mcpは無料で使えますか？
無料です。GPL-3.0のオープンソースで、npmから取得して使う分に費用はかかりません。コードを書くのは接続先のエージェントなので、Claude CodeやCursorなどの利用料金は別にかかります。
Claude Codeではどう設定しますか？
claude mcp addで--の後ろにnpx -y @pimzino/spec-workflow-mcp@latest /path/to/projectを書いて登録し、別のターミナルで--dashboard付きで起動したダッシュボードから承認します。プラグインとして/plugin marketplace add Pimzino/spec-workflow-mcpから入れる方法もあります。
spec-workflow-mcpとspecs-workflow-mcpは同じものですか？
別の製品です。Pimzino氏のspec-workflow-mcpはnpmで@pimzino/spec-workflow-mcp、kingkongshot氏のspecs-workflow-mcpはスコープなしのspec-workflow-mcpとして配布されています。ダッシュボードと承認画面があるのはPimzino氏の方です。
ダッシュボードのポートを5000から変えられますか？
変えられます。--dashboard --port 8080のように1024〜65535の番号を指定します。ダッシュボードは全プロジェクトで1つを共有するので、変えるのは5000が他のアプリと衝突するときだけで十分です。
MCPサーバーが起動しない、ツールが出てこないときは？
まず設定と同じ引数でターミナルから起動し、エラーを確かめます。「Unknown option」なら--AutoStartDashboardや--configなど削除済みの引数が残っています。エラーが出ないのに一覧に出ない場合は、初回のパッケージ取得がエージェントの起動タイムアウトを超えている可能性があるため、一度手で起動してキャッシュを作るか、Codexならstartup_timeout_secを延ばします。
