Build Claude Desktop Extensions with QuickMCP: Complete Guide

QuickMCP now supports building installable Claude Desktop extensions! Package your MCP servers as .mcpb files that users can install with a single click.

What Are Claude Desktop Extensions?

Claude Desktop extensions are packaged MCP servers that users can install through Claude's Settings > Extensions menu. Instead of manually editing JSON config files, users simply:

1. Download your .mcpb file
2. Install it through Claude Desktop
3. Configure credentials
4. Start using the tools

Why Build Extensions?

Traditional Approach (Manual)

Users have to:

• Install QuickMCP CLI
• Generate configuration
• Edit JSON files
• Find the Claude config location
• Manually add MCP server config
• Set environment variables
• Debug path issues
• Restart Claude Desktop

Extension Approach (Easy)

Users:

• Download .mcpb file
• Click to install
• Fill in credentials in a form
• Done!

Extensions reduce setup from 15 minutes to 30 seconds.

Installation

Make sure you have the latest QuickMCP CLI:

dotnet tool install -g QuickMCP.CLI
# or update existing
dotnet tool update -g QuickMCP.CLI

Building Your First Extension

Method 1: From Existing Config

If you already have a working MCP server config:

quickmcp build ce \
  -c ./my-api-config.json \
  --display-name "My API Tools" \
  --author-name "Your Name" \
  --ai-metadata \
  -k YOUR_GEMINI_API_KEY

This creates:

• manifest.json - Extension metadata
• my-api-config.json - MCP server configuration
• README.md - Documentation
• my-api.mcpb - Installable package

Method 2: From API Specification

Build from scratch using an OpenAPI spec:

quickmcp build ce \
  --spec-url https://api.stripe.com/openapi.json \
  --server-name "Stripe" \
  --auth bearer \
  --display-name "Stripe Payment Tools" \
  --author-name "Your Company" \
  --description "Query Stripe payments, customers, and subscriptions" \
  --ai-metadata \
  -k YOUR_GEMINI_API_KEY

Command Syntax

Basic Structure

quickmcp build ce [OPTIONS]

Aliases: build ce, build claude-extension, build claude

Essential Options

*Required unless using --ai-metadata which generates them

Additional Options

AI-Powered Metadata Generation

The --ai-metadata flag uses Google Gemini to:

Analyze Your Configuration

Gemini examines:

• API specification
• Authentication requirements
• Endpoint structure
• Tool descriptions

Generate User-Friendly Content

• Display names: "Stripe Payment Tools" instead of "stripe-api"
• Descriptions: Clear explanations of what the extension does
• Credential labels: "Stripe Secret Key (sk_...)" instead of "apiKey"
• Format hints: Shows expected credential formats
• Sensitivity flags: Marks which fields are secrets
• Keywords: SEO-optimized search terms

Example Without AI

{
  "displayName": "my-api",
  "description": "MCP server for my-api",
  "credentials": {
    "apiKey": {
      "label": "apiKey",
      "required": true
    }
  }
}

Example With AI

{
  "displayName": "Stripe Payment & Subscription Tools",
  "description": "Query payments, manage customers, and track subscriptions in Stripe. Read-only access to charges, customers, invoices, and balance.",
  "credentials": {
    "apiKey": {
      "label": "Stripe Secret Key",
      "description": "Your Stripe secret key (starts with sk_test_ or sk_live_)",
      "placeholder": "sk_test_...",
      "required": true,
      "sensitive": true,
      "format": "^sk_(test|live)_"
    }
  }
}

Much better user experience!

Getting a Gemini API Key

Free Tier

1. Go to: https://aistudio.google.com/app/apikey
2. Click "Get API key"
3. Create new project or select existing
4. Copy the key

Free tier includes:

• 15 requests per minute
• 1,500 requests per day
• More than enough for building extensions

Set Environment Variable

# Linux/macOS
export GOOGLE_API_KEY="your-gemini-key"

# Windows
set GOOGLE_API_KEY=your-gemini-key

Then omit -k flag:

quickmcp build ce -c config.json -m

Credential Placeholders

Extensions use placeholders for security:

Supported Formats

{
  "authentication": {
    "apiKey": "{{API_KEY}}",      // Double braces
    "token": "${BEARER_TOKEN}",   // Dollar sign + braces
    "secret": "{{CLIENT_SECRET}}"
  }
}

QuickMCP automatically detects these patterns and:

• Creates input fields in the installation UI
• Marks them as required
• Uses AI to generate helpful labels

Example Configuration

{
  "type": "openapi",
  "serverName": "stripe",
  "apiBaseUrl": "https://api.stripe.com",
  "authentication": {
    "type": "bearer",
    "settings": {
      "token": "{{STRIPE_SECRET_KEY}}"
    }
  }
}

When installed, Claude Desktop shows:

• Field label: "Stripe Secret Key"
• Description: "Your Stripe secret key (starts with sk_...)"
• Input type: Password (hidden)
• Validation: Checks format

Real Example: Building a Stripe Extension

Step 1: Build the Extension

quickmcp build ce \
  --spec-url https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json \
  --server-name "stripe" \
  --auth bearer \
  --exclude-paths "*/delete,*/remove" \
  --display-name "Stripe Payment Tools" \
  --author-name "Your Company" \
  --author-url "https://yourcompany.com" \
  --description "Query Stripe payments, customers, subscriptions, and more" \
  --keywords "stripe,payments,billing,subscriptions" \
  --ai-metadata \
  -k YOUR_GEMINI_API_KEY \
  -o ./stripe-extension

Step 2: Check Output

cd stripe-extension
ls

Output:

manifest.json
stripe-config.json
spec.json
README.md
stripe.mcpb

Step 3: Test Installation

1. Open Claude Desktop
2. Go to Settings > Extensions
3. Click "Install Extension"
4. Select stripe.mcpb
5. Fill in your Stripe secret key
6. Click "Install"
7. Restart Claude Desktop

Step 4: Verify It Works

Ask Claude:

"Show me my recent Stripe charges"

Claude should now have access to Stripe tools!

Distribution

Option 1: Direct Download

Host the .mcpb file on:

• Your website
• GitHub Releases
• Cloud storage (Dropbox, Google Drive)

Users download and install manually.

Option 2: Extension Repository (Future)

Claude may create an official extension marketplace where users can browse and install.

Option 3: Private Distribution

For internal company tools:

• Host on internal network
• Email to team members
• Add to company software portal

Manifest Structure

The generated manifest.json:

{
  "schema_version": "1.0",
  "type": "mcp_server",
  "name": "stripe",
  "display_name": "Stripe Payment Tools",
  "version": "1.0.0",
  "author": {
    "name": "Your Company",
    "url": "https://yourcompany.com"
  },
  "description": "Query Stripe payments, customers, subscriptions...",
  "homepage": "https://github.com/yourcompany/stripe-extension",
  "documentation": "https://docs.yourcompany.com/stripe",
  "license": "MIT",
  "keywords": ["stripe", "payments", "billing"],
  "configuration": {
    "credentials": {
      "STRIPE_SECRET_KEY": {
        "label": "Stripe Secret Key",
        "description": "Your Stripe secret key (starts with sk_...)",
        "required": true,
        "sensitive": true,
        "type": "string",
        "format": "^sk_(test|live)_",
        "placeholder": "sk_test_..."
      }
    }
  },
  "mcp_config_file": "stripe-config.json",
  "spec_file": "spec.json"
}

Troubleshooting

Error: "Author name required"

Cause: Missing --author-name without AI metadata.

Solution:

# Option 1: Add author name
quickmcp build ce -c config.json --author-name "Your Name"

# Option 2: Use AI to generate
quickmcp build ce -c config.json -m -k YOUR_GEMINI_KEY

Error: "Config not found"

Cause: Invalid path to configuration file.

Solution: Use absolute path:

quickmcp build ce -c /full/path/to/config.json

Issue: AI Not Generating Metadata

Check:

• Gemini API key is valid: echo $GOOGLE_API_KEY
• Internet connection is working
• You're within free tier limits (15 requests/min)

Test API key:

curl -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"test"}]}]}' \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp:generateContent?key=YOUR_KEY"

Issue: Extension Not Installing

Verify:

• .mcpb file exists and isn't corrupted
• Claude Desktop is updated to latest version
• You have write permissions to Claude config directory

Best Practices

1. Use AI Metadata

Always use --ai-metadata for better UX:

quickmcp build ce -c config.json -m -k $GOOGLE_API_KEY

2. Secure Credentials

Never hardcode secrets in config files:

❌ Bad:

{
  "authentication": {
    "apiKey": "sk_live_actual_secret_key"
  }
}

✅ Good:

{
  "authentication": {
    "apiKey": "{{STRIPE_SECRET_KEY}}"
  }
}

3. Filter Endpoints

Exclude dangerous operations:

--exclude-paths "*/delete,*/remove,/admin/*"

4. Test Before Distribution

Install your own extension first:

1. Build it
2. Install in Claude Desktop
3. Test all functionality
4. Fix any issues
5. Rebuild and redistribute

5. Document Well

Include clear README with:

• What the extension does
• How to get API credentials
• Required permissions/scopes
• Usage examples
• Troubleshooting tips

6. Version Properly

Use semantic versioning:

• 1.0.0 - Initial release
• 1.1.0 - New features
• 1.0.1 - Bug fixes
• 2.0.0 - Breaking changes

Next Steps

• Check CLI Reference for all commands
• Learn Authentication Methods
• Read Security Best Practices
• Try building extensions for Stripe, Twilio, or SendGrid

Claude Desktop extensions make MCP server distribution effortless. Build once, share everywhere!