# How to Add a Custom Marketplace to Claude Code

> Learn how to add a custom marketplace to Claude Code. Create a marketplace.json descriptor, host it in Git, and register your repository with a simple CLI command for extended functionality.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-02

---

**You can add a custom marketplace to Claude Code by creating a [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main//.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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) inside a directory called `.claude-plugin` at the root of your Git repository.

The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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:

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:

```bash
claude plugin marketplace add <owner>/<repo>

```

For example, to register the community marketplace as shown in the repository's [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md):

```bash
claude plugin marketplace add anthropics/claude-plugins-community

```

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

```bash
claude plugin marketplace update

```

## Adding Plugins to Your Marketplace

Each plugin listed in your [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) must have its own manifest file. Within the plugin's repository, create a [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json):

```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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) and resolves updated plugin manifests without requiring you to re-add the marketplace.