/creating-mcp-servers

MCPB Bundling Guide

Simple Method (Use This)

MCPB is just a ZIP archive with .mcpb extension.

# 1. Create manifest.json (see format below)
# 2. Bundle with zip
cd /home/claude
zip -r server-name.mcpb manifest.json server.py README.md
cp server-name.mcpb /mnt/user-data/outputs/

DO NOT use mcpb pack CLI - causes container crashes.

Bundle Structure

server-name.mcpb (ZIP archive)
├── manifest.json             # Required
├── server.py                 # Entry point
├── requirements.txt          # Optional
├── README.md                 # Optional
└── assets/                   # Optional

Manifest Format

{
    "manifest_version": "0.1",
    "name": "server-name",
    "version": "1.0.0",
    "description": "Server description",
    "author": "Your Name <email@example.com>",
    "license": "MIT",
    "server": {
        "type": "python",
        "entry_point": "server.py",
        "mcp_config": {
            "command": "uv",
            "args": [
                "run",
                "--with", "fastmcp>=2.0.0",
                "--with", "other-package>=1.0.0",
                "--", "server.py"
            ],
            "env": {
                "API_KEY": "",
                "API_URL": ""
            }
        }
    }
}

Field Descriptions

Top-level:

• manifest_version: MCPB spec version ("0.1")
• name: Package identifier (lowercase, hyphens, no spaces)
• version: Semantic version (MAJOR.MINOR.PATCH)
• description: One-line description
• author: Name and email
• license: SPDX identifier or "Proprietary"

Server configuration:

• type: "python" or "node"
• entry_point: Main server file
• mcp_config.command: Executable ("uv" for Python)
• mcp_config.args: Command-line arguments
• mcp_config.env: Environment variables (empty = user must provide)

Creating Bundles

Minimal Bundle

# Create manifest
cat > manifest.json << 'EOF'
{
    "manifest_version": "0.1",
    "name": "my-server",
    "version": "1.0.0",
    "description": "Brief server description",
    "server": {
        "type": "python",
        "entry_point": "server.py",
        "mcp_config": {
            "command": "uv",
            "args": ["run", "--with", "fastmcp>=2.0.0", "--", "server.py"]
        }
    }
}
EOF

# Create ZIP
zip -r my-server.mcpb manifest.json server.py README.md

# Move to outputs
cp my-server.mcpb /mnt/user-data/outputs/

With Dependencies

"args": [
    "run",
    "--with", "fastmcp>=2.0.0",
    "--with", "requests>=2.31.0",
    "--with", "pydantic>=2.0.0",
    "--", "server.py"
]

With Environment Variables

"mcp_config": {
    "command": "uv",
    "args": ["run", "--with", "fastmcp>=2.0.0", "--", "server.py"],
    "env": {
        "API_KEY": "",
        "API_URL": "",
        "DEBUG": "false"
    }
}

Installing Bundles

Claude Desktop

fastmcp install claude-desktop server.mcpb

Claude Code

fastmcp install claude-code server.mcpb

Manual

mkdir -p ~/mcp-servers/server-name
unzip server.mcpb -d ~/mcp-servers/server-name
# Add to MCP client config from manifest.json

Validation

# Check ZIP structure
unzip -l server.mcpb

# Extract and test
unzip -d /tmp/test server.mcpb
cd /tmp/test
uv run --with fastmcp server.py

Common Patterns

Single-File Server

simple-server.mcpb
├── manifest.json
└── server.py

Multi-File with Assets

complex-server.mcpb
├── manifest.json
├── server.py
├── requirements.txt
├── README.md
└── assets/
    └── schemas/

Environment-Configured

{
    "description": "Requires API_KEY and API_URL",
    "server": {
        "mcp_config": {
            "env": {
                "API_KEY": "",
                "API_URL": ""
            }
        }
    }
}

Best Practices

Manifest:

• Pin FastMCP version: "fastmcp>=2.0.0,<3.0.0"
• Document required env vars in description
• Include contact info in author field

Security:

• Environment variables for secrets (never hardcode)
• Empty values = user must provide

Dependencies:

• Pin major versions, allow minor updates
• Example: "requests>=2.31.0,<3.0.0"

Troubleshooting

Bundle extraction fails:

unzip -t server.mcpb  # Check integrity

Server won't start:

uv pip list
uv run --with fastmcp server.py

Environment variables not set:

export API_KEY="your-key"
export API_URL="https://api.example.com"
fastmcp install claude-desktop server.mcpb