spec-workflow-mcpは、AIコーディングエージェントに「要件定義 → 設計 → タスク分解 → 実装」の順序と承認ゲートを守らせるMCP（Model Context Protocol）サーバーです。GitHubのPimzino/spec-workflow-mcpで公開されているオープンソースで、npmパッケージ名は@pimzino/spec-workflow-mcp、2026年9月時点の最新版は2.2.5、GitHubのスターは約4,300です。ライセンスはGPL-3.0です。
この記事の記述は、npmで配布されている2.2.5のパッケージ（ツールの登録コード、同梱テンプレート、ダッシュボードのバンドル）を参照して確認しています。そのため、公式ドキュメントの記述と配布物の実装が食い違っている箇所も、確認手順つきで具体的に示します。導入手順、クライアント別のMCP設定、実際に公開されるツール、承認フロー、社内導入時のセキュリティ、他の仕様駆動開発ツールとの違いという順で整理します。
まとめ
- spec-workflow-mcpは専用IDEではなく、Claude CodeやCursorなど既存のMCP対応エージェントに後付けするサーバーです。成果物はプロジェクト直下の
.spec-workflow/にMarkdownとして残ります。 - 導入は
npxだけで済みます。ダッシュボードは--dashboardで既定ポート5000に立ち上がり、複数プロジェクトが1つのダッシュボードを共有します。 - 公式のツール一覧ドキュメントには13個のツール名が並びますが、npmで配布されている2.2.5が実際に登録するツールは5つです。文書の作成はツール呼び出しではなく、エージェントがファイルを直接書く方式に変わっています。
- ダッシュボードは127.0.0.1にバインドされ、レート制限や監査ログを備える一方、HTTPSとユーザー認証は未実装です。社内で共有するならリバースプロキシ側で設計する必要があります。2.2.4より前の版には任意ファイル読み取りの脆弱性があり、更新が必要です。
- Kiroは専用のデスクトップIDE、Spec KitはCLIツールキットで、spec-workflow-mcpは「今の開発環境に承認ワークフローだけを足す」選択肢です。
spec-workflow-mcpの全体像と3つの提供物
spec-workflow-mcpは、2025年8月7日にGitHubへ公開されたプロジェクトです。名前のとおりMCPサーバーとして動作し、AIエージェント側から呼び出されて仕様駆動開発（Spec-Driven Development、SDD）のワークフローを制御します。提供物は次の3つに分かれます。
- MCPサーバー本体：エージェントに対して、進めるべき手順と承認の状態を返します。npmから
npxで起動します。 - Webダッシュボード：ブラウザで仕様書・タスク・承認待ちを確認する画面です。サーバーとは別プロセスで起動します。
- VSCode拡張：Visual Studio Code Marketplaceで公開されている
Pimzino.spec-workflow-mcpです。ダッシュボードと同等の内容をサイドバーで扱えます。
ダッシュボードの表示言語は11言語に対応しています。配布物のフロントエンドバンドルを確認すると、英語・日本語・中国語・スペイン語・ポルトガル語・ドイツ語・フランス語・ロシア語・イタリア語・韓国語・アラビア語の言語キーが含まれており、既定は英語です。日本語のREADME（README.ja.md）もリポジトリに用意されています。
重要なのは、spec-workflow-mcpが独自のエディタや実行環境を持たない点です。コードを書くのは今使っているAIエージェントのままで、そこに「順序」と「承認」だけを差し込む構成になっています。生成された要件定義書・設計書・タスクリストは、プロジェクト直下の.spec-workflow/ディレクトリにMarkdownで蓄積されるため、そのままGit管理下に置けます。
仕様駆動開発におけるspec-workflow-mcpの役割
仕様駆動開発は、実装前に要件と設計を文書として確定させ、その文書を単一の参照元としてAIにコードを書かせる進め方です。手法そのものの背景や従来手法との比較は仕様駆動開発（SDD／Spec-Driven Development）とは？従来手法との違いとAI時代に注目される理由で扱っているため、ここではspec-workflow-mcpが担う部分に絞ります。
このツールが引き受けるのは、手法の解説ではなく手順の強制です。エージェントは各フェーズの文書を作ったあと、必ず承認を要求し、承認されるまで次のフェーズへ進めません。人間が「いいですよ」と言うまでAIが実装に着手しないという制約が、仕組みとして入ります。AIエージェントが要件の確認を飛ばして実装を始めてしまう問題に対して、プロンプトの工夫ではなくサーバー側の状態管理で対処する設計です。
もう一つの役割がテンプレートの供給です。配布物には要件定義（requirements）・設計（design）・タスク（tasks）の3種類に加え、プロジェクト全体の前提を書くステアリング文書として製品（product）・技術（tech）・構造（structure）の3種類、合計6つのMarkdownテンプレートが同梱されています。ステアリング文書に書いた方針は各フェーズでエージェントに読み込まれるため、コーディング規約やドメイン知識を毎回説明し直す必要がなくなります。
導入手順とダッシュボードの起動
インストール作業はほとんどありません。npxが使えるNode.js環境があれば動きます。なお、パッケージのpackage.jsonにはNode.jsのバージョン要件（engines）が指定されていないため、公式に下限が宣言されているわけではありません。実務上は、利用するAIエージェント側が要求するNode.jsのバージョンに合わせておけば問題ありません。
ダッシュボードの先行起動と既定ポート5000
CLIベースのエージェントから使う場合、ダッシュボードは必須です。次のコマンドで起動します。
npx -y @pimzino/spec-workflow-mcp@latest --dashboard既定ではポート5000で待ち受け、http://localhost:5000 でアクセスできます。ダッシュボードは1インスタンスだけ起動しておけば十分で、あとから起動した各プロジェクトのMCPサーバーはすべて同じダッシュボードに接続されます。プロジェクトごとに画面を立ち上げ直す必要はありません。
コマンドラインオプションは次のとおりです。
--dashboard：ダッシュボードのみを起動します。--port：ポート番号を1024から65535の範囲で指定します。5000が使えないときだけ使う想定です。--no-open：起動時にブラウザを自動で開かないようにします。--no-shared-worktree-specs：gitのワークツリーで仕様を共有せず、ワークツリーごとに持たせます。--help：使い方を表示します。
プロジェクト単位のサーバー起動とワークツリーでの保存先
ダッシュボードとは別に、対象プロジェクトのパスを渡してサーバーを起動します。
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1通常はこの起動をエージェント側のMCP設定に書いておくため、手で叩くのは動作確認のときだけです。gitのワークツリーで作業している場合、仕様の保存先は既定でメインリポジトリ側の.spec-workflow/になります。ワークツリーごとに仕様を分けたいときは前述の--no-shared-worktree-specs、保存先そのものを指定したいときは環境変数SPEC_WORKFLOW_SHARED_ROOTを使います。
ホームディレクトリが書き込めない環境での設定
グローバルな状態ファイル（プロジェクト一覧やセッション情報、グローバル設定）は既定で~/.spec-workflow-mcpに置かれます。Codex CLIをsandbox_mode=workspace-writeで使う場合のように、ホームディレクトリが読み取り専用になる環境では、環境変数で書き込み可能な場所へ逃がします。
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspaceVSCode拡張を使う場合
Visual Studio Codeで作業しているなら、拡張機能Pimzino.spec-workflow-mcpをマーケットプレイスから導入すると、仕様書の閲覧・タスクの進捗確認・承認操作をサイドバーから行えます。日常の確認と承認はVSCodeだけで回せます。拡張の最新は2026年1月28日更新のv1.1.7で、サーバー本体とは更新時期がずれるため、新しい機能を試すときは両方の版を確認してください。
クライアント別のMCP設定
MCP対応クライアントであれば設定の形は共通で、mcpServersにコマンドと引数を書くだけです。基本形は次のようになります。
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}Claude Codeの場合
Claude CodeはMCPに対応しているため、追加のCLIツールを挟む必要はありません。claude mcp addで直接登録します。
claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project途中の--は区切り記号で、これがないとプロジェクトパスがnpxへの引数として解釈されてしまいます。Windowsで動かない場合は、公式ドキュメントがcmd.exe経由の代替コマンドを案内しています。Claude Code自体の運用はClaude Codeの/simplifyとは？/code-reviewとの違いと/batchの使い方【2026年8月版】もあわせて参考にしてください。
Cursorの場合
Cursorの設定先はmcp.jsonです。プロジェクト単位で使うならプロジェクト直下の.cursor/mcp.json、全プロジェクトで使うならホーム配下の~/.cursor/mcp.jsonに、前掲のmcpServersのJSONをそのまま置けば有効になります。
ここは間違えやすい箇所です。spec-workflow-mcp側のREADMEはCursorの設定先をsettings.jsonと案内していますが、Cursorの公式ドキュメントが示す現行の設定先はmcp.jsonです。前章のツール一覧と同じく、ドキュメントが実態に追いついていないパターンなので、上流の記述をそのまま写さずCursor側の公式ドキュメントで確認してください。カスタムコマンドを置く.cursor/commands/ディレクトリはスラッシュコマンド（Cursorではその後Skillsへの移行が進んでいる機能）用のもので、いずれにせよMCPサーバーの登録先ではありません。ここを取り違えると、設定したつもりでツールが一覧に出てこない状態になります。
その他のクライアント
- Claude Desktop：
claude_desktop_config.jsonに追記します。MCPサーバーを起動する前に、ダッシュボードを--dashboardで別途起動しておく必要があります。 - Codex：
~/.codex/config.tomlにTOML形式で[mcp_servers.spec-workflow]として書きます。 - Windsurf：
~/.codeium/windsurf/mcp_config.jsonに追記します。 - OpenCode：
opencode.jsonのmcpセクションに、typeをlocalとして書きます。 - Cline・Continue・Augment Code：いずれも共通形式の
mcpServersで設定します。
MCPそのものの仕組みを先に押さえたい場合はMCP（Model Context Protocol）とは？AIと外部ツールをつなぐ標準規格の仕組みをわかりやすく解説を参照してください。
4段階ワークフローと実際に公開されるツール5つ
使い始めは設定後の会話からで、公式は「Create a spec for user authentication」のように依頼する例を挙げています。そこから、Requirements（要件定義）、Design（設計）、Tasks（タスク分解）、Implementation（実装）の順に進みます。各フェーズで文書が作られ、承認されるまで次に進みません。仕様の名前はkebab-caseで、一度に扱う仕様は1つという制約もガイドに明記されています。
公式ドキュメント13ツールと配布物5ツールの食い違い
ここが最も注意が必要な点です。リポジトリのツール一覧ドキュメント（docs/TOOLS-REFERENCE.md）には、create-spec-docやmanage-tasks、get-spec-context、get-template-contextなど13個のツールが説明されています。しかし、npmで配布されている2.2.5が実際に登録するツールは次の5つだけです。
spec-workflow-guide：ワークフロー全体の手順をエージェントに読み込ませます。最初に呼ぶ想定のツールです。steering-guide：ステアリング文書の作り方を返します。spec-status：仕様とタスクの進捗状況を返します。approvals：承認の要求・状態確認・削除を1つにまとめたツールです。log-implementation：実装内容のログを記録します。
この5つは、配布物のdist/tools/index.jsにある登録関数で確認できます。手元で確かめるなら次の手順です。
npm pack @pimzino/[email protected]
tar xzf pimzino-spec-workflow-mcp-2.2.5.tgz
cat package/dist/tools/index.js文書作成用のツールが消えているのは、方式が変わったためです。現在はspec-workflow-guideが返す手順書に従って、エージェントが.spec-workflow/specs/（仕様名）/requirements.mdのようなファイルを直接書き出します。ツールを呼んで文書を作らせるのではなく、テンプレートを読んでファイルを作り、そのファイルパスをapprovalsに渡す流れです。
ただし、2.2.5に同梱されているガイド文の中にはget-template-contextやcreate-spec-docといった旧ツール名への言及が残っています。エージェントがこの記述に引きずられて存在しないツールを呼ぼうとすることがあるため、ツールが見つからないというエラーが出ても設定ミスとは限りません。その場合はテンプレートを直接読ませる指示を足すと進みます。
食い違いはツール一覧だけではありません。設定ガイドは.spec-workflow/config.tomlによる設定ファイルと--configオプションを案内していますが、2.2.5の--helpの出力に--configは含まれず、TOMLを読み込むモジュールも配布物のどこからも呼ばれていません（参照しているのはテストコードだけです）。同じく設定ガイドはポートの既定を「一時ポート」と書いている箇所がありますが、実際のコードは指定が無ければ5000を使います。設定はコマンドライン引数と環境変数で行うのが確実です。
承認フローとダッシュボードでの操作
承認はapprovalsツールの3つの操作で回ります。エージェントがaction: requestで承認を要求し、レビュー担当者がダッシュボードかVSCode拡張で内容を確認します。エージェント側はaction: statusで状態を問い合わせ続け、承認が下りたら次のフェーズへ進みます。承認せずに修正コメントを返せば、エージェントは文書を書き直して再度承認を要求します。不要になった承認要求はaction: deleteで片付けます。
ダッシュボードでは、仕様ごとのカードに進捗バーと各文書の状態が並びます。日本語表示での状態は「承認済み」「保留中」「修正が必要」「却下」で、ステアリング文書には「未作成」のバッジが付きます。タスクの完了数と全体数も表示されるため、どこで止まっているかがひと目で分かります。log-implementationで記録された実装ログは検索でき、コードの統計情報も残るので、後から「この機能はどのタスクで、どんな判断のもとに実装されたのか」を追えます。レビュー担当がリポジトリを開かずに要件と設計を確認できるため、非エンジニアのプロダクト担当者を承認者に立てる運用も現実的です。
社内導入前に確認したいセキュリティ設定
ダッシュボードはWebサーバーとして動くため、チームで使うなら公開範囲の設計が必要です。公式ドキュメントは実装済みの対策と未実装の項目を明示しています。
先に版の確認をおすすめします。2.2.4（2026年3月2日）で任意ファイル読み取りの脆弱性が修正されています。承認要求に渡すfilePathに絶対パスや..を含めると、ダッシュボードにアクセスできる相手がプロジェクト外のシステムファイルを読み出せた問題です（Issue #201）。修正では、ツールの入力・承認の作成・パスの解決という3段階で絶対パスとパストラバーサルを弾く実装が入りました。社内に古い版が残っている場合は、機能面の理由がなくても更新が必要です。
実装済みの対策は次のとおりです。
- ローカルホストへのバインド：既定で127.0.0.1にバインドされ、ネットワークに露出しません。
- レート制限：クライアントごとに1分あたり120リクエストまでに制限されます。
- 監査ログ：タイムスタンプ・実行者・操作・結果を含む構造化JSONログが出力されます。
- セキュリティヘッダー：X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、CSP、Referrer-Policyが付与されます。
- CORS制限：既定でローカルホスト由来のオリジンに限定されます。
- コンテナの堅牢化：Dockerでの実行時は非rootユーザー、読み取り専用ファイルシステム、ケーパビリティの削除、リソース制限が設定されています。
一方、HTTPS/TLSとユーザー認証は未実装と明記されています。回避策として公式が案内しているのは、ダッシュボードを127.0.0.1に置いたまま、nginxやApacheをリバースプロキシとして前段に立て、そこでTLS終端とBasic認証またはOAuth2を担う構成です。ファイアウォールでアクセス元を絞ることも推奨されています。
隔離した環境で動かしたい場合は、リポジトリのcontainersディレクトリにDocker Composeの構成が用意されており、コンテナのポート5000をホストに公開して.spec-workflowだけをボリュームとしてマウントする形で起動できます。
もう一点、企業で使うならライセンスがGPL-3.0であることも確認事項です。開発支援ツールとして起動して使う分には自社製品のライセンスに影響しませんが、ソースコードを改変して社外へ配布する場合は条件が変わります。フォークして社内向けに手を入れる計画があるなら、法務の確認を先に通しておくのが安全です。
開発の継続性も判断材料になります。npmの最新版2.2.5は2026年3月2日の公開で、以降そのままです。リポジトリのREADME冒頭には、作者が個人的な事情で一時的に開発を離れている旨の告知が2026年9月時点で掲示されています。単独の作者が開発するツールを社内の標準プロセスに組み込むかどうかは、この点も含めて判断してください。
Kiro・Spec Kit・cc-sddとの形態の違い
仕様駆動開発を支援するツールは複数あり、形態がそれぞれ異なります。前提として押さえておきたいのは、spec-workflow-mcpだけが「既存エージェントに後付けするMCPサーバー」だという点です。
| ツール | 形態 | 導入の単位 |
|---|---|---|
| spec-workflow-mcp | MCPサーバー | 今のエージェントに追加 |
| Kiro | デスクトップIDEほか | AWS製。IDEやCLIを導入 |
| Spec Kit | CLIツールキット | GitHub製。CLIで初期化 |
| cc-sdd | Agent Skills配布型 | エージェントにスキル配置 |
KiroはAWSが提供する仕様駆動型のAI IDEです。公式のインストール手順ではmacOS・Windows・Linux向けのインストーラーをダウンロードして導入する形が案内されており、デスクトップIDEに加えてCLI、Webアプリ、モバイルアプリという複数の入口があります。クラウド上に開発環境が自動構築される類のサービスと説明されることがありますが、そうではなく手元にインストールして使うのが基本形です。主たる使い方がIDE本体の置き換えになる点で、既存環境を維持したまま足せるspec-workflow-mcpとは導入の重さが異なります（CLIやWebアプリという軽い入口も用意されています）。Agent HooksやAgent Steeringといった自動化機構を含めた全体像はKiroとは？AWS製の仕様駆動AI IDEの特徴・料金・使い方を解説【2026年版】で解説しています。
Spec KitはGitHubが公開しているオープンソースのツールキットです。CLIとテンプレート群という構成で、/speckit.constitutionコマンドで生成するconstitution.mdにプロジェクトの原則と開発ガイドラインを書き、AIの出力に一貫性を持たせる考え方が特徴です。承認ワークフローやダッシュボードは持たないため、プロセスの統制よりも軽さと柔軟さを取りたい場合に向きます。導入手順はSpec Kit（GitHub）とは？仕様駆動開発の使い方・インストール・コマンドを徹底解説にまとめています。
cc-sddはgotalab/cc-sddで公開されているOSSで、npmパッケージ名もcc-sddです。リポジトリの説明では「承認済みの仕様を長時間の自律実装へつなげる、最小構成で適応性のあるSDDハーネス」と位置づけられており、Claude Code、Codex、Cursor、Copilot、Windsurf、OpenCode、Gemini CLI、AntigravityといったエージェントにAgent Skillsを配る方式を採ります。サーバーを常駐させるspec-workflow-mcpとは実装方針が違い、エージェント側のスキルとして入る点が対照的です。
ここで挙げていないOpenSpecとは？AI仕様駆動開発(SDD)の導入手順・CLI操作とSpec Kit比較を含め、横並びの比較と用途別の選び分けは仕様駆動開発ツール比較｜Spec Kit・Kiro・cc-sdd・OpenSpec・Tesslの違いと選び方で扱っています。
よくある質問
spec-workflow-mcpは無料で使えますか？
無料で使えます。GPL-3.0のオープンソースとして公開されており、npmから取得して利用する分に費用はかかりません。ただしコードを書くのは接続先のAIエージェントなので、Claude CodeやCursorなど利用するエージェント側の料金は別途かかります。
Claude Codeで使うにはどう設定しますか？
claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/projectを実行して登録します。Claude Codeは標準でMCPに対応しているため、別のCLIツールを併用する必要はありません。CLIから使う場合は、別のターミナルで--dashboardを付けてダッシュボードも起動しておきます。
ダッシュボードのポートを5000から変更できますか？
できます。--portオプションで1024から65535の範囲の番号を指定します。公式ドキュメントは、5000が使用中でない限り既定のまま使うことを推奨しています。
VSCodeだけで日常の操作は回せますか？
回せます。拡張機能Pimzino.spec-workflow-mcpを入れると、仕様書の閲覧・タスクの進捗確認・承認操作をサイドバーから行えます。ブラウザのダッシュボードを開く必要があるのは、VSCode以外のエディタやCLIエージェントを使う場合です。
spec-workflow-mcpはどんなチームに向きますか？
今の開発環境を変えずに、AIが実装へ進む前の承認を人間が明示的に握りたいチームに向きます。エージェントの選定が固まっていない、あるいはメンバーごとにClaude CodeとCursorが混在しているような状況でも、MCPサーバーとして共通に載せられる点が利点です。逆に、承認ゲートを必要としない少人数の開発では、手数が増えるだけになることもあります。
