gh-phaezer-claude-mkt-plugins-mcp/commands/deploy-mcp.md

description, argument-hint

description	argument-hint
Deploy MCP server locally or with Docker	Deployment target (local/docker/both)

Deploy MCP Server

Deploy an MCP server for local usage (Claude Desktop, pip/npm) or Docker containers.

Usage

/deploy-mcp [target]

Arguments:

• target: Deployment target - local, docker, or both (optional, defaults to local)

Examples:

/deploy-mcp local
/deploy-mcp docker
/deploy-mcp both

What This Command Does

This command handles the complete deployment workflow for MCP servers:

• Local deployment (Claude Desktop integration, pip/npm packages)
• Docker containerization
• Configuration management
• Documentation creation
• Troubleshooting guides

Workflow Steps

Step 1: Detect Project Details

Analyze the project:

1. Language: Python or TypeScript?
2. Server Type: stdio, SSE, or both?
3. Dependencies: What external services are needed?
4. Configuration: What environment variables required?

Step 2: Launch Deployment Engineer Agent

Use the Task tool to launch mcp-deployment-engineer agent.

Agent Task:

Create deployment configuration for MCP server:

Project: [project name]
Location: [project path]
Language: [Python/TypeScript]
Transport: [stdio/SSE/both]
Target: [local/docker/both]

Requirements:
1. Local Deployment:
   - Claude Desktop configuration
   - Package configuration (pip/npm)
   - Installation documentation
   - Environment variable management

2. Docker Deployment (if requested):
   - Dockerfile optimized for size and security
   - Docker Compose configuration
   - Health checks
   - Volume management

3. Documentation:
   - Installation guide
   - Configuration guide
   - Troubleshooting guide
   - Usage examples

Deliverables:
- Claude Desktop config example
- Package configuration (pyproject.toml/package.json)
- Dockerfile and docker-compose.yml (if requested)
- .env.example with all variables
- Complete README.md
- Troubleshooting guide

Step 3: Prepare for Local Deployment

Python Package Preparation:

1. Verify pyproject.toml:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-mcp-server"
version = "0.1.0"
description = "MCP server for [purpose]"
requires-python = ">=3.11"
dependencies = [
    "fastmcp>=0.1.0",
    # other dependencies
]

[project.scripts]
my-mcp-server = "my_mcp_server.__main__:main"

2. Create distribution:

# Install build tools
pip install build

# Build package
python -m build

# Test installation locally
pip install dist/my_mcp_server-0.1.0-py3-none-any.whl

# Test running
my-mcp-server

TypeScript Package Preparation:

1. Verify package.json:

{
  "name": "my-mcp-server",
  "version": "0.1.0",
  "main": "./build/index.js",
  "bin": {
    "my-mcp-server": "./build/index.js"
  },
  "files": [
    "build",
    "README.md"
  ],
  "scripts": {
    "build": "tsc",
    "prepare": "npm run build"
  }
}

2. Build and test:

# Build
npm run build

# Test locally
npm link
my-mcp-server

# Or test with npx
npx .

Step 4: Create Claude Desktop Configuration

Generate Claude Desktop config for both uvx/npx and local installations:

Python (uvx - Recommended):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Python (local installation):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "API_KEY": "your-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

TypeScript (npx - Recommended):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

TypeScript (local installation):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/path/to/project/build/index.js"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

Step 5: Create Docker Configuration (if requested)

Python Dockerfile:

FROM python:3.11-slim as builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Copy and install
COPY pyproject.toml README.md ./
COPY src/ ./src/
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir .

# Production stage
FROM python:3.11-slim

WORKDIR /app

# Copy from builder
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin

# Non-root user
RUN useradd -m -u 1000 mcpuser && \
    chown -R mcpuser:mcpuser /app

USER mcpuser

# Health check
HEALTHCHECK --interval=30s --timeout=10s \
    CMD python -c "import sys; sys.exit(0)"

CMD ["my-mcp-server"]

TypeScript Dockerfile:

# Build stage
FROM node:18-slim as builder

WORKDIR /app

COPY package*.json tsconfig.json ./
COPY src/ ./src/
RUN npm ci && npm run build && npm prune --production

# Production stage
FROM node:18-slim

WORKDIR /app

COPY --from=builder /app/build ./build
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# Non-root user
RUN useradd -m -u 1000 mcpuser && \
    chown -R mcpuser:mcpuser /app

USER mcpuser

HEALTHCHECK --interval=30s --timeout=10s \
    CMD node -e "process.exit(0)"

CMD ["node", "build/index.js"]

docker-compose.yml:

version: '3.8'

services:
  mcp-server:
    build: .
    container_name: my-mcp-server
    restart: unless-stopped
    environment:
      - API_KEY=${API_KEY}
      - LOG_LEVEL=${LOG_LEVEL:-info}
    # For stdio
    stdin_open: true
    tty: true
    # For SSE
    # ports:
    #   - "3000:3000"
    volumes:
      - ./data:/app/data
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

Step 6: Create Environment Configuration

Create .env.example:

# API Keys (REQUIRED)
API_KEY=your-api-key-here
GITHUB_TOKEN=ghp_your_github_token

# Database (if applicable)
DATABASE_URL=postgresql://user:pass@localhost:5432/db

# Server Configuration
SERVER_NAME=my-mcp-server
LOG_LEVEL=info

# Rate Limiting
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60

# Feature Flags
ENABLE_CACHING=true
CACHE_TTL=300

Create .env for local development:

cp .env.example .env
# Edit .env with actual values

Step 7: Create Comprehensive Documentation

README.md:

# My MCP Server

[Brief description]

## Features

- ✅ [Feature 1]
- ✅ [Feature 2]
- ✅ [Feature 3]

## Installation

### Quick Start (Claude Desktop)

1. Install the server:
   ```bash
   uvx my-mcp-server  # Python
   # or
   npx my-mcp-server  # Node.js

2. Configure Claude Desktop:

   Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "my-server": {
         "command": "uvx",
         "args": ["my-mcp-server"],
         "env": {
           "API_KEY": "your-api-key"
         }
       }
     }
   }
   

3. Restart Claude Desktop

Local Installation

Python:

pip install my-mcp-server
my-mcp-server

Node.js:

npm install -g my-mcp-server
my-mcp-server

Docker

# Build
docker build -t my-mcp-server .

# Run with stdio
docker run -i \
  -e API_KEY=your-key \
  my-mcp-server

# Or use docker-compose
docker-compose up -d

Configuration

Environment Variables

Variable	Required	Description	Default
API_KEY	Yes	API key for service	-
LOG_LEVEL	No	Logging level	info
RATE_LIMIT	No	Requests per minute	100

Getting API Keys

1. Go to [service provider]
2. Create account
3. Generate API key
4. Add to configuration

Available Tools

[List and document all tools]

Troubleshooting

Server not starting

• Check environment variables are set
• Verify API key is valid
• Check logs for specific errors

Tools not appearing in Claude

• Restart Claude Desktop
• Check configuration file syntax
• Verify server starts manually

Development

# Clone
git clone [repo]

# Install
pip install -e .[dev]  # or npm install

# Run tests
pytest  # or npm test

# Run locally
python -m my_mcp_server  # or npm run dev

License

MIT

**TROUBLESHOOTING.md:**
```markdown
# Troubleshooting Guide

## Installation Issues

### Python: Command not found

**Problem**: `my-mcp-server: command not found`

**Solutions**:
1. Verify installation: `pip list | grep my-mcp-server`
2. Check PATH includes pip bin directory
3. Reinstall: `pip install --force-reinstall my-mcp-server`

### Node.js: Module not found

**Problem**: `Cannot find module 'my-mcp-server'`

**Solutions**:
1. Verify installation: `npm list -g my-mcp-server`
2. Reinstall: `npm install -g my-mcp-server`
3. Try with npx: `npx my-mcp-server`

## Configuration Issues

[More troubleshooting content...]

Step 8: Test Deployment

Local Testing:

1. Test package installation:

# Python
pip install -e .
my-mcp-server --help

# TypeScript
npm install
npm run build
node build/index.js --help

2. Test with MCP Inspector:

mcp-inspector python -m my_mcp_server
# or
mcp-inspector node build/index.js

3. Test in Claude Desktop:

• Add to configuration
• Restart Claude Desktop
• Verify tools appear
• Test tool execution

Docker Testing:

# Build image
docker build -t my-mcp-server:test .

# Test stdio
docker run -i -e API_KEY=test my-mcp-server:test

# Test with inspector
docker run -i my-mcp-server:test | mcp-inspector -

# Check image size
docker images my-mcp-server:test

Step 9: Create Deployment Checklist

# Deployment Checklist

## Pre-Deployment
- [ ] All tests passing
- [ ] Security review complete
- [ ] Documentation complete
- [ ] Version number updated
- [ ] CHANGELOG updated

## Package Configuration
- [ ] pyproject.toml/package.json correct
- [ ] Dependencies specified
- [ ] Entry points configured
- [ ] Build succeeds
- [ ] Package installs locally

## Claude Desktop
- [ ] Config example created
- [ ] Environment variables documented
- [ ] Installation instructions clear
- [ ] Tested with real Claude Desktop

## Docker (if applicable)
- [ ] Dockerfile optimized
- [ ] Image builds successfully
- [ ] Image size reasonable (<500MB)
- [ ] Health check works
- [ ] Non-root user configured
- [ ] docker-compose.yml provided

## Documentation
- [ ] README complete
- [ ] API documentation clear
- [ ] Configuration documented
- [ ] Troubleshooting guide provided
- [ ] Examples included

## Testing
- [ ] Tested locally
- [ ] Tested with MCP Inspector
- [ ] Tested in Claude Desktop
- [ ] Tested with Docker (if applicable)

Step 10: Provide Deployment Summary

✓ Deployment Configuration Complete: [project-name]

Local Deployment:
  ✓ Claude Desktop config created
  ✓ Package configuration ready
  ✓ Installation instructions documented

  Installation:
    Python: uvx my-mcp-server
    Node.js: npx my-mcp-server

  Claude Desktop Config:
    Location: ~/Library/Application Support/Claude/claude_desktop_config.json
    Example: ./claude-desktop-config.example.json

Docker Deployment:
  ✓ Dockerfile created (optimized, 180MB)
  ✓ docker-compose.yml created
  ✓ Health checks configured
  ✓ Non-root user configured

  Build: docker build -t my-mcp-server .
  Run: docker-compose up -d

Documentation:
  ✓ README.md complete
  ✓ TROUBLESHOOTING.md created
  ✓ .env.example provided
  ✓ Usage examples included

Next Steps:
1. Test deployment locally:
   - Install: uvx my-mcp-server
   - Configure Claude Desktop
   - Restart Claude Desktop
   - Test tools

2. (Optional) Publish package:
   Python: python -m build && twine upload dist/*
   Node.js: npm publish

3. (Optional) Deploy Docker:
   docker-compose up -d

Files created:
  - claude-desktop-config.example.json
  - Dockerfile
  - docker-compose.yml
  - .env.example
  - README.md
  - TROUBLESHOOTING.md

Success Criteria

• Deployment configuration created
• Claude Desktop config example provided
• Package configuration verified
• Docker configuration created (if requested)
• Environment variables documented
• Comprehensive documentation created
• Installation tested
• User has clear deployment instructions

This command provides production-ready deployment configuration for MCP servers across multiple platforms.