mcp-deploy-template

Template repository for creating MCP servers compatible with mcp-deploy.

Quick Start

1. Click "Use this template" on GitHub to create a new repo

2. Clone your new repo locally

3. Find-and-replace these placeholder values:

   Placeholder	Replace with	Files
   my-mcp-server	Your worker name (kebab-case)	package.json, mcp-deploy.json, wrangler.jsonc, packages/deploy/src/index.ts
   my-mcp	Your library package name	packages/mcp/package.json, packages/deploy/package.json, packages/deploy/src/index.ts
   deploy-my-mcp	Your deploy package name	packages/deploy/package.json
   MyMCP	Your Durable Object class name (PascalCase)	mcp-deploy.json, wrangler.jsonc, packages/deploy/src/index.ts
   My MCP Server	Human-readable name	mcp-deploy.json

4. Add your tools in packages/mcp/src/index.ts

5. Add secrets to mcp-deploy.json if your tools need API keys

6. Update the Env type in packages/deploy/src/index.ts to match

Architecture

packages/
├── mcp/      # Transport-agnostic MCP tools library
│             # Reusable with stdio, Cloudflare Workers, or any MCP transport
└── deploy/   # Cloudflare Worker wrapper for mcp-deploy
              # Wraps the library in a Durable Object with health check

Development

npm install
npm run dev            # Start local dev server (wrangler)

Publishing a Release

When you push a version tag, GitHub Actions automatically builds and creates a release with the required assets (worker.mjs + mcp-deploy.json):

git tag v0.1.0
git push origin v0.1.0

Then in mcp-deploy, add your repo:

mcp-deploy add your-user/your-repo

Adding Secrets

If your MCP needs API keys or other secrets, add them to mcp-deploy.json:

{
  "secrets": [
    {
      "key": "API_KEY",
      "label": "Your API Key",
      "type": "password",
      "required": true,
      "helpText": "Get your key from ...",
      "helpUrl": "https://...",
      "placeholder": "sk-..."
    }
  ]
}

Then add the matching env var to the Env type in packages/deploy/src/index.ts and pass it to registerTools().

Adding Config Options

For user-configurable settings (not secrets), use the config array in mcp-deploy.json:

{
  "config": [
    {
      "key": "ENABLED_FEATURES",
      "label": "Enabled Features",
      "type": "multiselect",
      "options": [
        { "value": "feature_a", "label": "Feature A" },
        { "value": "feature_b", "label": "Feature B" }
      ],
      "default": "feature_a,feature_b",
      "helpText": "Select which features to enable"
    }
  ]
}

Making it a Template

After pushing, go to Settings > General and check "Template repository" to enable the "Use this template" button.