voc-mcp

# VOC OpenAPI MCP Installer

[English](README.md) | [简体中文](README.zh-CN.md)

Install a curated seven-tool VOC OpenAPI MCP server for Amazon review insights,
feedback tagging, and listing optimization in local AI clients.

Built for e-commerce operators, consumer-insights teams, product researchers,
and AI agents that need authorized review data and repeatable VOC workflows.

## Usage

```bash
curl -fsSL https://open.voc.ai/install.sh | bash
```

Windows PowerShell:

```powershell
irm https://open.voc.ai/install.ps1 | iex
```

Alternatively, use the npm package directly:

```bash
npx voc-openapi-mcp@latest setup
```

Codex users can also install the general-purpose VOC OpenAPI query skill:

```bash
npx voc-openapi-mcp@latest setup --with-skill
```

The skill is written to `~/.agents/skills/voc-openapi/SKILL.md` only when Codex is detected. The uninstaller removes only installer-managed versions that have not been modified by the user.

By default, the installer registers the agents detected on the local machine. It currently supports:

- Claude Code (CLI; writes to `~/.claude.json`)
- Claude Desktop (desktop app; detects the macOS app or Windows `%LOCALAPPDATA%\AnthropicClaude`, writes to `claude_desktop_config.json`, and bridges the remote MCP server through `mcp-remote`)
- Cursor (desktop app or CLI launcher; detects the macOS app or Windows `%LOCALAPPDATA%\Programs\cursor`, both using `~/.cursor/mcp.json`)
- Windsurf (desktop app or CLI launcher; detects the macOS app or Windows `%LOCALAPPDATA%\Programs\Windsurf`, both using `~/.codeium/windsurf/mcp_config.json`)
- Gemini CLI (writes to `~/.gemini/settings.json`)
- Codex (CLI and Desktop both use `~/.codex/config.toml`)

List the agents detected on the local machine:

```bash
curl -fsSL https://open.voc.ai/install.sh | bash -s -- --list-agents
```

Windows PowerShell:

```powershell
& ([scriptblock]::Create((irm https://open.voc.ai/install.ps1))) -ListAgents
```

Register every supported agent (the installer detects installed clients automatically by default, so this is usually unnecessary):

```bash
npx voc-openapi-mcp@latest setup --all-agents
```

Default configuration:

- Codex: `$CODEX_HOME/config.toml`, or `~/.codex/config.toml` when `CODEX_HOME` is not set
- Claude Code: `~/.claude.json`
- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (or `%APPDATA%\Claude\claude_desktop_config.json` on Windows)
- Cursor: `~/.cursor/mcp.json`
- Windsurf: `~/.codeium/windsurf/mcp_config.json`
- Gemini CLI: `~/.gemini/settings.json`
- MCP server name: `voc-openapi`
- MCP URL: `https://open.voc.ai/mcp/catalog`
- Authentication header: `X-API-Key`
- Catalog endpoint: seven curated, outcome-oriented tools
- Codex MCP startup timeout: `120` seconds

The installer updates the corresponding MCP server configuration in place and does not create `.bak` backup files.

## Options

```bash
voc-mcp setup \
  --api-base https://open.voc.ai \
  --name voc-openapi \
  --with-skill \
  --config ~/.codex/config.toml
```

You can also skip browser authorization and provide an API key directly:

```bash
VOC_OPENAPI_API_KEY=voc_live_sk_xxx npx voc-openapi-mcp@latest setup
```

## Preview

```bash
npx voc-openapi-mcp@latest setup --api-key voc_live_sk_xxx --dry-run
```

> **Note:** To support a one-command setup, the API key is currently stored as plain text in the local MCP client configuration file.

## Example result

<a href="docs/assets/voc-mcp-product-analysis-full.png">
  <img src="docs/assets/voc-mcp-product-analysis.png" alt="VOC OpenAPI MCP product analysis result covering listing data, review insights, pain points, competitive positioning, and recommended actions" width="900">
</a>

This single agent request combines product and listing data, review insights, customer pain points, competitive positioning, and recommended actions. Click the image to view the full result.

## Capabilities

- Fetch current or historical Amazon reviews.
- Analyze sentiment, pain points, and themes.
- Generate listing improvements from customer feedback.
- Tag feedback and product listings into structured taxonomies.

See [TOOLS.md](TOOLS.md) for all seven tools, input fields, credit costs, and
task-creating side effects.

## Privacy, permissions, and support

The hosted server only receives the selected tool inputs and the `X-API-Key`
required for the authorized VOC account. The installer writes only the selected
AI client's MCP configuration and the optional VOC skill. Review
[PRIVACY.md](PRIVACY.md) and [SECURITY.md](SECURITY.md) before installation.

- [Product website](https://open.voc.ai)
- [Privacy Policy](https://www.voc.ai/privacy-policy)
- [Terms and Conditions](https://www.voc.ai/terms-and-conditions)
- [Support](https://www.voc.ai/support)
- [Official Registry metadata](server.json)

## License

The installer source code is licensed under the [Apache License 2.0](LICENSE).
The hosted VOC OpenAPI service and its business capabilities remain subject to
the [VOC Terms and Conditions](https://www.voc.ai/terms-and-conditions).