# envato-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the
[Envato API](https://build.envato.com/). It lets MCP-compatible AI clients
(Claude Desktop, Cursor, and others) search the Envato Market catalog, look up
author statistics, inspect a buyer's purchases, and read the authenticated
user's account details.

## Features

- **Catalog search** — full-text item search, popular items, and category
  listings across Envato Market sites (ThemeForest, CodeCanyon, etc.).
- **Author stats** — public user info, item counts by site, badges, and
  market-wide totals.
- **Buyer / purchases** — list your purchases, fetch download links, and verify
  purchase codes.
- **Account info** — the authenticated user's account, username, and email.

Every tool validates its input with [zod](https://zod.dev) and returns the raw
Envato JSON response. API errors (including `401`/`403` auth failures and `429`
rate limiting) are surfaced as clear, actionable messages.

## Requirements

- Node.js 18 or newer.
- An Envato personal token (see below).

## Getting an Envato token

1. Go to <https://build.envato.com/create-token/>.
2. Select the permissions you need. For example:
   - *View and search Envato sites* — catalog tools.
   - *View your Envato Account username* / *email* — account tools.
   - *View your items' sales history* / *List purchases you've made* — buyer
     tools.
   - *Download your purchased items* — download links.
3. Create the token and copy it. You will pass it to the server as the
   `ENVATO_TOKEN` environment variable.

## Usage

Run directly with `npx` (no install required):

```bash
ENVATO_TOKEN=your-token-here npx envato-mcp
```

The server communicates over stdio and is intended to be launched by an MCP
client rather than used interactively.

### Claude Desktop

Add the server to your `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "envato": {
      "command": "npx",
      "args": ["-y", "envato-mcp"],
      "env": {
        "ENVATO_TOKEN": "your-token-here"
      }
    }
  }
}
```

### Cursor

Add the server to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "envato": {
      "command": "npx",
      "args": ["-y", "envato-mcp"],
      "env": {
        "ENVATO_TOKEN": "your-token-here"
      }
    }
  }
}
```

After saving, restart the client so it picks up the new server.

## Tools

### Catalog search

| Tool | Description | Arguments |
| --- | --- | --- |
| `envato_search_items` | Search the catalog for items matching a term. | `term` (string, required), `site` (string, optional), `page` (int, optional), `page_size` (int 1–100, optional) |
| `envato_popular_items` | Most popular items for a site. | `site` (string, e.g. `themeforest`) |
| `envato_categories` | All categories for a site. | `site` (string, e.g. `codecanyon`) |

### Author stats

| Tool | Description | Arguments |
| --- | --- | --- |
| `envato_user_info` | Public account details for a user. | `username` (string) |
| `envato_user_items_by_site` | Number of items a user sells per site. | `username` (string) |
| `envato_user_badges` | Badges earned by a user. | `username` (string) |
| `envato_market_totals` | Total users and items across Envato Market. | _none_ |

### Buyer / purchases

| Tool | Description | Arguments |
| --- | --- | --- |
| `envato_list_purchases` | List the authenticated buyer's purchases. | `filter_by` (enum, optional), `page` (int, optional) |
| `envato_download_link` | Download URL for a purchased item. | `item_id` (int) |
| `envato_verify_purchase` | Verify a purchase code and return sale details. | `code` (string) |

### Account info

| Tool | Description | Arguments |
| --- | --- | --- |
| `envato_account` | The authenticated user's account details. | _none_ |
| `envato_my_username` | The authenticated user's username. | _none_ |
| `envato_my_email` | The authenticated user's email. | _none_ |

## Development

```bash
npm install        # install dependencies
npm run dev        # rebuild on change (tsup --watch)
npm run typecheck  # type-check with tsc (no emit)
npm run lint       # lint with ESLint
npm run build      # bundle to dist/ with tsup
```

The build outputs an executable ESM bundle to `dist/index.js` with a Node
shebang, wired up as the `envato-mcp` bin.

## License

[MIT](./LICENSE) © 2026 Scott McAuley