How to Add a Custom Marketplace to Claude Code

You can add a custom marketplace to Claude Code by creating a marketplace.json descriptor inside a .claude-plugin directory, hosting it in a Git repository, and registering the repository via the CLI command claude plugin marketplace add <owner>/<repo>.

Claude Code consumes marketplace definitions—JSON files that catalog available plugins—to extend its core functionality. The anthropics/claude-plugins-community repository provides the canonical implementation, hosting its marketplace definition at /.claude-plugin/marketplace.json. Creating your own marketplace allows you to distribute internal tools, proprietary integrations, or curated plugin collections to your team through version-controlled infrastructure.

Creating the Marketplace Descriptor

Every custom marketplace requires a specific file structure that Claude Code recognizes. You must create a file named marketplace.json inside a directory called .claude-plugin at the root of your Git repository.

The marketplace.json file must contain a JSON object with a plugins array. Each entry in this array requires specific fields that define how Claude Code resolves and displays the plugin:

• name: The unique plugin identifier (e.g., myorg/my-plugin)
• source: An object containing repo (owner/repo format), ref (git tag or branch), and path (directory containing the plugin manifest)
• Optional metadata: description, icon URL, and tags array

The repository enforces schema validation through CI actions located at .github/actions/validate-plugins/, which use Zod definitions to ensure your marketplace structure is valid before merging.

Marketplace Configuration Example

Create the following structure in your repository root:

{
  "plugins": [
    {
      "name": "myorg/example-plugin",
      "source": {
        "repo": "myorg/example-plugin",
        "ref": "v1.2.3",
        "path": ".claude-plugin"
      },
      "description": "A sample Claude Code plugin for internal workflows",
      "icon": "https://example.com/icon.svg",
      "tags": ["demo", "utility"]
    }
  ]
}

Save this as .claude-plugin/marketplace.json. The source.path field specifies the directory within the plugin repository where Claude Code expects to find the individual plugin.json manifest file.

Hosting Your Custom Marketplace

Host your marketplace descriptor in a Git repository—public or private—that Claude Code can access. The system reads the marketplace directly from the repository; no package registry, npm publishing, or additional deployment steps are required. Ensure the .claude-plugin/marketplace.json file exists on your default branch (usually main), as Claude Code resolves the file from the repository root at HEAD.

Registering the Marketplace with Claude CLI

Once your marketplace is hosted, register it with your local Claude Code installation using the CLI. This command adds the repository to Claude Code's marketplace index:

claude plugin marketplace add <owner>/<repo>

For example, to register the community marketplace as shown in the repository's README.md:

claude plugin marketplace add anthropics/claude-plugins-community

After registration, optionally refresh the marketplace to pull the latest plugin versions and metadata:

claude plugin marketplace update

Adding Plugins to Your Marketplace

Each plugin listed in your marketplace.json must have its own manifest file. Within the plugin's repository, create a plugin.json file inside a .claude-plugin directory.

The community repository provides concrete examples. The tres-finance-plugin defines its manifest at tres-finance-plugin/.claude-plugin/plugin.json:

{
  "name": "tres-finance/tres-finance-plugin",
  "version": "0.1.0",
  "description": "Finance-related Claude Code skills",
  "entrypoint": "cli",
  "type": "skills",
  "commands": [
    {
      "name": "tres-report-create",
      "description": "Create a financial report"
    }
  ]
}

Another reference implementation exists at testdino/.claude-plugin/plugin.json. Required fields include name, version, description, entrypoint (the execution target), type (category), and commands (available subcommands).

Summary

• Create a .claude-plugin/marketplace.json file at your repository root following the schema enforced by the validation actions in .github/actions/validate-plugins/
• Define plugin entries with name, source object (containing repo, ref, and path), and optional metadata fields
• Host the marketplace in a Git repository without requiring additional publishing infrastructure
• Register the marketplace using claude plugin marketplace add <owner>/<repo> to make plugins available in Claude Code
• Refresh periodically with claude plugin marketplace update to fetch new versions referenced by updated git refs

Frequently Asked Questions

What file structure does Claude Code require for custom marketplaces?

Claude Code expects a file at .claude-plugin/marketplace.json in the root of your Git repository. This file must contain a JSON object with a plugins array, where each plugin specifies its name and source (including repo, ref, and path properties).

How do I validate my marketplace.json before deployment?

The anthropics/claude-plugins-community repository includes CI validation actions at .github/actions/validate-plugins/ that use Zod schemas to verify marketplace structure. Run these actions in your repository to ensure your marketplace.json meets the required specifications before merging changes.

Can I use a private Git repository for my custom marketplace?

Yes. Claude Code can consume marketplaces from private repositories as long as your local Git configuration and Claude CLI authentication have appropriate access to read the repository contents. The CLI resolves the marketplace.json file using your existing Git credentials.

How do I update plugins after adding a custom marketplace?

When plugin authors release new versions by updating the git ref (tag or branch) in their repository, run claude plugin marketplace update to refresh the local cache. This command pulls the latest marketplace.json and resolves updated plugin manifests without requiring you to re-add the marketplace.

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