Claude Plugins Community marketplace.json File Format: Complete Schema Guide

The marketplace.json file is a JSON array containing plugin metadata objects with required fields like name, description, version, author, repository, and manifestPath, plus optional fields for icons, checksums, tags, visibility, and licensing.

The marketplace.json file serves as the canonical catalogue for all community-published Claude plugins in the anthropics/claude-plugins-community repository. Located at /.claude-plugin/marketplace.json, this single JSON document powers the plugin marketplace UI and is strictly validated by continuous integration workflows to ensure every entry conforms to the expected schema.

Core Schema and Required Fields

Each element in the marketplace.json array represents a distinct plugin entry. The following fields are mandatory for every plugin listing:

• name – Human-readable identifier (e.g., "Preserve Session")
• description – Full description displayed in the marketplace interface
• version – Semantic version string (e.g., "1.2.3")
• author – Individual or organization responsible for the plugin
• repository – Absolute URL to the GitHub repository hosting the source code
• manifestPath – Relative path to the plugin's plugin.json file (e.g., ".claude-plugin/plugin.json")

A minimal valid entry appears as:

{
  "name": "Preserve Session",
  "description": "Keeps Claude Code sessions alive across project moves, renames, and copies",
  "version": "1.0.0",
  "author": "anthropic",
  "repository": "https://github.com/anthropics/claude-plugins-community",
  "manifestPath": ".claude-plugin/plugin.json"
}

Optional Metadata Fields

The schema supports additional fields to enhance discoverability and security:

• icon – URL or relative path to an SVG/PNG asset for the marketplace UI
• sha256 – SHA-256 hash of the plugin bundle for integrity verification
• tags – Array of classification strings (e.g., ["finance", "analysis"]) to aid search
• visibility – Access control string; either "public" (default) or "private"
• license – SPDX license identifier for the plugin's legal terms

CI Validation and Schema Enforcement

The repository enforces schema compliance through automated validation defined in /.github/workflows/validate-plugins.yml. The CI executes claude plugin validate <marketplace.json> against the assembled catalogue, utilizing validation logic implemented in /.github/actions/validate-plugins/lib/common.sh.

Invalid entries—whether from missing required fields or malformed data types—cause the workflow to fail, preventing corrupted metadata from reaching the production marketplace. This gatekeeping ensures that every plugin referenced in /.claude-plugin/marketplace.json maintains data integrity and matches the structure defined in the corresponding plugin.json manifests.

How to Parse marketplace.json Programmatically

Since the file is a standard JSON array, you can consume it using any language. Below are reference implementations for Node.js and Python.

Loading the Catalogue in Node.js

import fs from 'fs';
import path from 'path';

const marketplacePath = path.resolve('.claude-plugin/marketplace.json');
const raw = fs.readFileSync(marketplacePath, 'utf-8');
const plugins = JSON.parse(raw);

plugins.forEach(p => {
  console.log(`${p.name} – v${p.version}`);
});

Filtering Plugins by Tag in Python

import json
import pathlib

data = json.loads(pathlib.Path('.claude-plugin/marketplace.json').read_text())
finance_plugins = [p for p in data if 'finance' in p.get('tags', [])]

for p in finance_plugins:
    print(f"{p['name']} ({p['version']}): {p['description']}")

Summary

• The marketplace.json file format is a JSON array located at /.claude-plugin/marketplace.json in the anthropics/claude-plugins-community repository.
• Required fields include name, description, version, author, repository, and manifestPath.
• Optional fields support icon, sha256, tags, visibility, and license metadata.
• The CI validation workflow in /.github/workflows/validate-plugins.yml enforces schema compliance using claude plugin validate.
• Each entry's manifestPath points to a plugin.json file (typically at /.claude-plugin/plugin.json) that contains the actual plugin implementation details.

Frequently Asked Questions

What is the root structure of the marketplace.json file?

The root structure is a JSON array ([...]) where each element is a JSON object representing a single plugin. It is not a keyed object but a sequential list, allowing the marketplace to iterate through available plugins programmatically.

Which fields are mandatory in the marketplace.json schema?

Six fields are strictly required: name, description, version, author, repository, and manifestPath. The CI validation脚本 in /.github/actions/validate-plugins/lib/common.sh will reject any entry missing these core properties.

How does the CI validate the marketplace.json file format?

The validation workflow runs automatically via /.github/workflows/validate-plugins.yml, executing the command claude plugin validate against the marketplace.json file. This process checks field presence, data types, and URL validity, failing the build if any entry violates the schema.

What is the relationship between marketplace.json and plugin.json?

The marketplace.json file contains catalogue metadata and a manifestPath field that points to each plugin's individual plugin.json file. While marketplace.json tracks high-level information like versioning and tags for the marketplace UI, plugin.json (referenced via the manifest path) defines the plugin's runtime behavior and command specifications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}