Deno MCP Template Repo

Deno MCP サーバーテンプレート

本番環境向けの MCP サーバーを TypeScript で構築するための、必要な機能がすべてそろった出発点です。

クローンしてセットアップを実行すれば、すぐに開発を始められます。STDIO および HTTP トランスポート、セキュリティミドルウェア、永続状態、サンドボックス化された実行環境、CI/CD ワークフローに加え、JSR パッケージ、ネイティブバイナリ、DXT 拡張機能、Deno Deploy でのホスティングなど、必要なあらゆる配布形式に対応しています。

このテンプレートを選ぶ理由

2 分以内に、動作する MCP サーバーを手に入れられます。 おもちゃのようなものではなく、レート制限、CORS、セッション管理、TLS サポート、構造化ログがすでに組み込まれた実用的なサーバーです。

Deno なら、ほかのランタイムでは得られない強力な機能を利用できます。 組み込みの KV データベース（Postgres や Redis のセットアップは不要）、ネイティブの cron スケジューリング、マイクロ VM 上でのサンドボックス化されたコード実行、バイナリへのコンパイル、Deploy による一級のホスティングに対応しています。このテンプレートでは、これらすべてを活用できます。

どこへでも、どんな方法でもデプロイできます。 1 つのコードベースから、次のものを生成できます。

• Cursor、Claude Desktop、または任意の MCP クライアント向けのローカル STDIO サーバー
• Streamable HTTP トランスポートを使用するリモート HTTP サーバー
• 誰でもクローンせずに deno run できる JSR パッケージ
• 単独で動作するネイティブバイナリ（ランタイム不要）
• Claude Desktop にワンクリックでインストールできる DXT 拡張機能
• マネージドクラウドホスティング向けの Deno Deploy アプリ

AI エージェントに扱いやすいコードベースです。 ファイルが小さく（200 LOC 未満）、機能ごとに構成され、型が明示されています。コーディングエージェントは、コンテキストが過負荷になることなく、コードを理解して拡張できます。

クイックスタート

# Install Deno (if needed)
curl -fsSL https://deno.land/install.sh | sh

# Create your project from template
gh repo create my-mcp-server --template phughesmcr/deno-mcp-template
cd my-mcp-server

# One-time setup -- renames placeholders, then self-destructs
deno task setup

# Start the server (STDIO + HTTP on localhost:3001)
deno task start

# Or launch with MCP Inspector for interactive testing
deno task dev

任意の MCP クライアントから接続します。

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "deno",
      "args": ["run", "-A", "/absolute/path/to/main.ts"]
    }
  }
}

これで完了です。ツール、リソース、プロンプト、タスクワークフローを備えた MCP サーバーが起動しました。

JSR サブパスインポート

このパッケージを JSR に公開すると、プログラム全体（main.ts）またはより限定されたエントリーポイントをインポートできます。

• jsr:@scope/name — main.ts と同じです（CLI エントリーポイント）。
• jsr:@scope/name/mcp — createMcpServer、mcpServerDefinition、コンテキスト／サブスクリプションヘルパー、および関連するエクスポートを含みます。リクエストを処理する前に、ホスト側で引き続き Deno KV（およびその他の共有サービス）を開く必要があります。これは createApp と同様です。
• jsr:@scope/name/app — main.ts をコピーせずに STDIO + HTTP ホストを組み込むための createApp です。

トランスポートごとの McpServer インスタンスと共有コンテキストについては、.cursor/rules/project.mdc の Architecture を参照してください。

含まれるもの

すぐに使えるインフラストラクチャ

内容	方法	場所
2 種類のトランスポート	1 つのアプリから STDIO と Streamable HTTP を提供	src/app/
HTTP ミドルウェア	レート制限、CORS、任意のベアラー認証（/mcp-elicitation/* のブラウザーページには適用されません）、セキュリティヘッダー、タイムアウト、セッション	src/app/http/hono.ts
永続状態	Deno KV — ローカルでは設定不要、Deploy では組み込み	src/kv/
セッションの再開	ストリーム復旧用の KV ベースのイベントストア	src/app/http/kvEventStore.ts
バックグラウンドタスク	MCP の実験的タスク：KV TaskStore と TaskMessageQueue、および遅延エコーのデモ用 listenQueue ワーカー	src/mcp/tasks/
スケジュール済みジョブ	定期メンテナンス用の Deno.cron	src/app/cron.ts
サンドボックスでの実行	信頼できないコード用の @deno/sandbox マイクロ VM	src/mcp/tools/sandbox.ts
MCP Apps（インタラクティブ UI）	@modelcontextprotocol/ext-apps を介したサンプルツールと ui:// HTML バンドル	mcp-ui/、src/mcp/apps/、static/mcp-apps/
CI/CD ワークフロー	CI、リリース、デプロイ、JSR 公開用の GitHub Actions	.github/workflows/
設定管理	検証とマージを行う CLI フラグと環境変数	src/app/cli.ts
権限の事前チェック	具体的なガイダンスを示す、起動時のフェイルファストチェック	src/app/permissions.ts

MCP 機能の例（独自のものに置き換えてください）

プロンプト： review-code、language-snippet

リソース： hello://world、greetings://{name}、counter://value（KV ベース、サブスクライブ可能）

ツール： elicit-input、elicit-form-wizard（2 段階のフォーム引き出し）、url-elicitation-demo（URL モードの引き出し。セッションがある場合のみ Streamable HTTP を使用）、fetch-website-info（対応クライアントではテキストと任意の MCP Apps UI）、increment-counter、log-message、notify-list-changed、poem（サンプリング）、execute-code（サンドボックスで実行）

タスクのワークフロー（実験的）： delayed-echo、guided-poem（引き出しとサンプリングのパイプライン）

これらは、引数付きプロンプト、静的および動的リソース、サブスクリプション、サンプリング、フォームと URL による引き出し、通知、リスト変更イベント、KV による永続化、サンドボックスでの実行、非同期タスクのパターン、MCP Apps UI の例（fetch-website-info）を網羅しています。参考にしたうえで、独自のドメインロジックに置き換えてください。

自分用にカスタマイズする

まず deno task setup を実行してください。プロジェクト全体のパッケージ名、スコープ、メタデータが一括で書き換えられます。

編集を始める場所

1. src/shared/constants/ -- サーバー名、説明、バージョン、デフォルト値
2. src/mcp/tools/ -- ツールを追加します（既存のパターンに従ってください）
3. src/mcp/apps/ -- インタラクティブ UI を追加する場合は、MCP App のツール／リソースを登録します（@modelcontextprotocol/ext-apps/server）
4. mcp-ui/ -- MCP App HTML 用の Vite バンドル（deno task build:mcp-ui を実行します。Deno が npm の依存関係をインストールして Vite を実行します。mcp-ui/README.md を参照してください）
5. src/mcp/resources/ -- リソースを追加します
6. src/mcp/prompts/ -- プロンプトを追加します
7. src/mcp/serverDefinition.ts -- 機能リスト、ケイパビリティフラグ、派生する SERVER_CAPABILITIES（src/shared/constants/mcp.ts から再エクスポート）
8. src/mcp/mod.ts -- サーバーの構築（登録は定義に従います）
9. src/app/http/hono.ts -- CORS、ミドルウェア、ルートを調整します

削除するもの

不要なサンプルファイルを src/mcp/tools/、src/mcp/resources/、src/mcp/prompts/ から削除します（MCP Apps を使わない場合は、src/mcp/apps/ と mcp-ui/ も削除します）。対応する mod.ts のバレルエクスポートと、src/mcp/mod.ts 内の登録も更新します。これで完了です。

HTTP セキュリティ

• 認証： MCP_HTTP_BEARER_TOKEN（または --http-bearer-token）を設定すると、クライアントは /mcp に Authorization: Bearer … または x-api-key: … を送信する必要があります。CI や本番環境のテンプレートでは、MCP_REQUIRE_HTTP_AUTH=true を設定すると、トークンが設定されていない場合に起動に失敗します。/mcp-elicitation/ 配下のパスでは、通常のブラウザータブで MCP トークンなしに URL モードのエリシテーションページを開けるよう、意図的にベアラー認証を省略しています。
• リンク用の公開 URL： リバースプロキシの背後にある場合は、ユーザーがブラウザーで開く https:// オリジンを MCP_PUBLIC_BASE_URL（または --public-base-url）に設定すると、URL エリシテーションリンクがデプロイ環境に合ったものになります。設定されていない場合、サーバーはバインドアドレスから URL を導出します（src/shared/publicBaseUrl.ts を参照）。
• 公開範囲： トークンなしでループバック以外のホスト名にバインドすると、警告がログに記録されます。そのポートにアクセスできるすべてのユーザーが MCP を利用できます。トークンを使うか、リバースプロキシで TLS と認証を終端してください。
• すべてのインターフェース： 0.0.0.0 または :: でリッスンするには、--dnsRebinding と --host / MCP_ALLOWED_HOSTS が必要です（起動時に検証されます）。
• CORS： ワイルドカードの * オリジンは許可されません。明示的なオリジンを指定してください（例：MCP_ALLOWED_ORIGINS）。
• レート制限： MCP_TRUST_PROXY=true の場合、制限はプロキシのクライアント IP ヘッダーに従います（実際のプロキシの背後でのみ安全です）。ソケット IP もセッションもないリクエストには、より低い上限が適用されます（src/shared/constants/http.ts の RATE_LIMIT_UNKNOWN_CLIENT）。
• fetch-website-info： デフォルトでは、パブリックな HTTPS URL のみ許可されます（プライベート IP、localhost、リンクローカル、.internal などはブロックされます）。リダイレクトは同じチェックを適用しながら手動で追跡されます。デモで http:// を許可するには、MCP_DOMAIN_TOOL_ALLOW_HTTP=1 を設定してください。MCP Apps 対応ホストでは、インライン UI として ui://deno-mcp-template/fetch-website-info.html を読み込めます。それ以外のホストでは、ツールの結果に JSON テキストが返されます。

コピーして使える変数については .env.example を参照してください。

公開する

配布方法を選ぶ

目的	コマンド	出力
STDIO 経由でローカル実行	deno task start	直接プロセス
HTTP 経由で提供	deno task start	localhost:3001/mcp
JSR パッケージとして公開	deno publish	jsr:@scope/package
ネイティブバイナリをコンパイル	deno task compile:all	dist/server/
DXT としてパッケージ化	deno task dxt:all	dist/server.dxt
クラウドにデプロイ	deno deploy --prod	Deno Deploy URL

プラットフォーム固有のコンパイル／DXT タスクも利用できます：compile:win、compile:mac:arm64、compile:mac:x64、compile:linux:x64、compile:linux:arm64（および対応する dxt:* バリエーション）。

コンパイルタスクでは static/ ディレクトリがバンドルされるため、バイナリは作業ディレクトリに依存せず静的ルートを提供できます。

DXT の前提条件： npm install -g @anthropic-ai/dxt を実行して、DXT CLI を一度インストールしてください。パッケージ化する前に static/dxt-manifest.json を更新してください。

JSR の前提条件： JSR.io のアカウントが必要です。JSR で公開する予定がない場合は、.github/workflows/publish.yml を削除してください。

クライアント設定の例

STDIO（Cursor、Claude Desktop など）：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "deno",
      "args": ["run", "-A", "/absolute/path/to/main.ts"]
    }
  }
}

mcp-remote を使った HTTP：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3001/mcp"]
    }
  }
}

直接 HTTP（URL 対応クライアント）：

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "http://localhost:3001/mcp",
      "headers": { "origin": "http://localhost:3001" }
    }
  }
}

JSR パッケージ：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "deno",
      "args": ["run", "-A", "jsr:@your-scope/your-package"]
    }
  }
}

コンパイル済みバイナリ：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/absolute/path/to/binary"
    }
  }
}

Claude Code：

claude mcp add my-mcp-server /absolute/path/to/binary
claude mcp add --transport http my-mcp-server http://localhost:3001/mcp

Deno Deploy にデプロイする（任意）

# Create app (one-time)
deno deploy create \
  --org <YOUR_ORG> \
  --app <YOUR_APP> \
  --source local \
  --runtime-mode dynamic \
  --entrypoint main.ts \
  --build-timeout 5 \
  --build-memory-limit 1024 \
  --region us

# Deploy
deno deploy --prod

自動デプロイを有効にするには、GitHub Actions のシークレットに DENO_DEPLOY_TOKEN、DENO_DEPLOY_ORG、DENO_DEPLOY_APP を設定してください。Deploy を使用しない場合は、.github/workflows/deploy.yml を削除してください。

本番環境向けチェックリスト

• deno task setup を実行し、すべてのプレースホルダー名が置き換えられていることを確認します
• リリースしないデモ用のツール／リソース／プロンプトを削除するか、置き換えます
• static/.well-known/openapi.yaml と static/dxt-manifest.json を更新します
• 環境に合わせて MCP_ALLOWED_ORIGINS と MCP_ALLOWED_HOSTS を設定します
• src/app/http/kvEventStore.ts を本番環境に対応したイベントストアに置き換えます（同梱のものはデモ用です）
• 本番環境では deno run -A を明示的な権限に切り替えます
• 外部へのツール呼び出しで使用する --allow-net の範囲を確認します
• CI とホスティングプロバイダーで環境変数を設定します
• deno task ci を実行します（フォーマット、リント、型チェック、テスト）

設定

変数	フラグ	デフォルト	説明
MCP_NO_HTTP	--no-http	false	HTTP サーバーを無効にします
MCP_NO_STDIO	--no-stdio	false	STDIO トランスポートを無効にします
MCP_HOSTNAME	-n	localhost	HTTP の待ち受けホスト名
MCP_PORT	-p	3001	HTTP の待ち受けポート
MCP_PUBLIC_BASE_URL	--public-base-url		ブラウザーのリンク（URL elicitation）に使用する公開 http(s):// オリジン。末尾にスラッシュを付けないでください
MCP_TLS_CERT	--tls-cert		PEM 証明書のパス（--tls-key が必要です）
MCP_TLS_KEY	--tls-key		PEM 秘密鍵のパス（--tls-cert が必要です）
MCP_HEADERS	-H		レスポンスヘッダー（コレクション）
MCP_JSON_RESPONSE	--json-response	false	JSON のみのレスポンス（SSE を無効にします）
MCP_DNS_REBINDING	--dnsRebinding	false	トランスポートレベルの Origin／Host チェックを有効にします（ループバックへのバインドでは、すでに Host 検証が行われます）
MCP_ALLOWED_ORIGINS	--origin		許可する CORS オリジン（コレクション）
MCP_ALLOWED_HOSTS	--host		許可するホスト名（コレクション）
MCP_KV_PATH	--kv-path		カスタム Deno KV データベースのパス
MCP_MAX_TASK_TTL_MS	--max-task-ttl-ms	86400000（24h）	実験的な MCP タスクでクライアントが要求できる最大 TTL（ms）。KvTaskStore で上限が設定されます（最小 60s、最大 1y。src/shared/validation/config.ts を参照）
DENO_DEPLOY_TOKEN			デプロイトークン（execute-code サンドボックスツールで必要）

CLI フラグは環境変数より優先されます。コレクション値（-H、--origin、--host）は両方のソースから統合されます。

コレクション設定の例

コレクション形式の値は、.env でカンマ区切りの文字列として設定できます。

MCP_HEADERS=x-api-key:demo,cache-control:no-store
MCP_ALLOWED_ORIGINS=http://localhost:6274,https://app.example.com
MCP_ALLOWED_HOSTS=localhost,127.0.0.1,app.example.com

または、CLI フラグを繰り返して指定します。

deno task start -- \
  -H "x-api-key:demo" \
  -H "cache-control:no-store" \
  --origin "http://localhost:6274" \
  --origin "https://app.example.com" \
  --host "localhost" \
  --host "app.example.com"

完全なオリジン（例：https://example.com）には --origin を、ホスト名または IP アドレス（例：example.com、127.0.0.1）には --host を使用します。

開発

コマンド	説明
deno task start	サーバーを起動します
deno task dev	MCP Inspector とウォッチモードを使って起動します
deno task build:mcp-ui	MCP App の HTML を static/mcp-apps/ にビルドします（Deno と mcp-ui/deno.lock を使用。Node.js は不要です）
deno task ci	build:mcp-ui の後に、フォーマット、リント、型チェック、テストを実行します
deno task test:integration	統合テストを実行します
deno task test:coverage	カバレッジレポート付きでテストを実行します
deno task bench	ベンチマークを実行します

deno task ci は最初に build:mcp-ui を実行します。このタスクは mcp-ui/ 内で Deno のみを使ってインストールし、Vite を実行します（mcp-ui/README.md を参照）。このステップに必要なのは Deno だけです。

ランタイム権限

アプリは起動時に必要な権限を検証し、実行可能な対処法を示してすぐに失敗します。本番環境では -A よりも明示的な権限を使用してください。

# HTTP + STDIO (local defaults)
deno run --env-file=.env \
  --allow-env --allow-read --allow-write --allow-sys \
  --allow-net=localhost:3001 \
  main.ts

# STDIO only (no HTTP listener)
deno run --env-file=.env \
  --allow-env --allow-read --allow-write --allow-sys \
  main.ts --no-http

fetch-website-info など、ネットワークを使用するツールを残す場合は、接続先を --allow-net に含めてください。

ロックファイルと再現性

このテンプレートでは、依存関係を決定論的に解決するために deno.lock を管理しています。

• ロックデータを更新します：deno install --entrypoint main.ts --frozen=false
• ロックされた依存関係の解決を検証します（CI）：deno install --frozen --entrypoint main.ts
• 依存関係を変更した際は deno.lock をコミットします。

プロジェクト構成

main.ts                     # Entry point
src/
  app/                      # Runtime shell: transports, HTTP, KV, cron, signals
  mcp/                      # MCP server: tools, resources, prompts, tasks, apps
  shared/                   # Constants, types, validation, utilities
mcp-ui/                     # Vite + ext-apps front-end for MCP App HTML bundles
static/                     # Static files, OpenAPI spec, DXT manifest, mcp-apps/*.html
scripts/                    # Setup, build, and packaging helpers
test/                       # Integration tests and benchmarks
.github/workflows/          # CI, release, deploy, publish

注釈付きのソースツリー、トランスポートの内部構造、開発上の注意事項については、 .cursor/rules/project.mdc を参照してください。

その他

利便性を高めるファイルが含まれています。

• .cursor/rules/ -- このプロジェクト用の Cursor エージェントルール
• .cursor/skills/ -- ツール、リソース、プロンプトの実装に役立つエージェントスキル（以下を参照）
• .cursorignore -- .gitignore に加えて、Cursor が除外するファイルを指定します
• .vscode/ -- 推奨拡張機能、デフォルトのフォーマッターとしての Deno
• .github/ -- CI/CD ワークフロー、スポンサー設定、課題テンプレート
• CLAUDE.md -- オプションの Claude Code プロジェクトコンテキスト
• CODE_OF_CONDUCT.md、CONTRIBUTING.md など -- GitHub のコミュニティ管理ファイル

スキル

.cursor/skills/ ディレクトリには、このテンプレートで MCP の機能を実装する際に Cursor をガイドするエージェントスキルが含まれています。各スキルでは、ファイルのテンプレート、登録手順、型シグネチャ、動作するサンプルを提供します。

スキル	対象範囲
implementing-mcp-tools	標準ツール、サンプリング、フォームおよび URL による情報収集、リソース連携ツール、通知
implementing-mcp-resources	静的リソース、KV 連携リソース、リソーステンプレート、サブスクリプション
implementing-mcp-prompts	静的引数または動的補完を備えたプロンプト

これらのスキルは、関連する場合に Cursor によって自動的に読み込まれます。「新しいツールを追加して」や「リソースを作成して」とエージェントに依頼すると、プロジェクトのパターンに沿って実装します。

参考資料

• MCP の仕様
• MCP Apps / @modelcontextprotocol/ext-apps（インタラクティブなツール UI）
• MCP の概念
• Deno のドキュメント
• Deno Deploy
• Deno Sandbox
• Hono

謝辞

このテンプレートを使用する場合は、修正や機能の提供、リポジトリへのスター付け、スポンサーとしての支援をご検討ください。

これは公式の Deno プロジェクトではありません。

ライセンス

MIT -- これはライブラリではなくテンプレートです。本番環境にリリースする前に変更することを想定しています。