677 lines
13 KiB
Markdown
677 lines
13 KiB
Markdown
---
|
|
description: Deploy MCP server locally or with Docker
|
|
argument-hint: 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:**
|
|
```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:**
|
|
```bash
|
|
# 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:**
|
|
```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:**
|
|
```bash
|
|
# 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):**
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"my-mcp-server": {
|
|
"command": "uvx",
|
|
"args": ["my-mcp-server"],
|
|
"env": {
|
|
"API_KEY": "your-api-key-here",
|
|
"LOG_LEVEL": "info"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Python (local installation):**
|
|
```json
|
|
{
|
|
"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):**
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"my-mcp-server": {
|
|
"command": "npx",
|
|
"args": ["-y", "my-mcp-server"],
|
|
"env": {
|
|
"API_KEY": "your-api-key-here",
|
|
"LOG_LEVEL": "info"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**TypeScript (local installation):**
|
|
```json
|
|
{
|
|
"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:**
|
|
```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:**
|
|
```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:**
|
|
```yaml
|
|
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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with actual values
|
|
```
|
|
|
|
### Step 7: Create Comprehensive Documentation
|
|
|
|
**README.md:**
|
|
```markdown
|
|
# 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`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"my-server": {
|
|
"command": "uvx",
|
|
"args": ["my-mcp-server"],
|
|
"env": {
|
|
"API_KEY": "your-api-key"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
3. Restart Claude Desktop
|
|
|
|
### Local Installation
|
|
|
|
**Python:**
|
|
```bash
|
|
pip install my-mcp-server
|
|
my-mcp-server
|
|
```
|
|
|
|
**Node.js:**
|
|
```bash
|
|
npm install -g my-mcp-server
|
|
my-mcp-server
|
|
```
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Python
|
|
pip install -e .
|
|
my-mcp-server --help
|
|
|
|
# TypeScript
|
|
npm install
|
|
npm run build
|
|
node build/index.js --help
|
|
```
|
|
|
|
2. **Test with MCP Inspector:**
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```markdown
|
|
# 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.
|