setup-polar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polar Setup Wizard

Polar 设置向导

Interactive setup guide to get Polar payments working in your project.

帮助您在项目中启用Polar支付功能的交互式设置指南。

Setup Flow

设置流程

Follow these steps in order:

按顺序遵循以下步骤：

Step 1: Check MCP Availability

步骤1：检查MCP可用性

First, check if the Polar MCP server is available. Try listing products or organizations using MCP tools.

If MCP tools work: Skip to Step 3.

If MCP not available: Continue to Step 2.

首先，检查Polar MCP服务器是否可用。尝试使用MCP工具列出产品或组织。

如果MCP工具可用： 跳至步骤3。

如果MCP不可用： 继续步骤2。

Step 2: Install Polar MCP

步骤2：安装Polar MCP

Guide the user to install the Polar MCP server based on their environment:

Claude Code:

bash

undefined

根据用户的环境引导其安装Polar MCP服务器：

Claude 代码：

bash

undefined

Production

claude mcp add --transport http "Polar" "https://mcp.polar.sh/mcp/polar-mcp"

Sandbox (recommended for setup)

claude mcp add --transport http "Polar Sandbox" "https://mcp.polar.sh/mcp/polar-sandbox"


**Cursor** (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "Polar Sandbox": {
      "url": "https://mcp.polar.sh/mcp/polar-sandbox"
    }
  }
}

After installation, the user must:

Restart their editor/CLI
Authenticate when prompted (redirects to polar.sh)

Once authenticated, verify MCP works by listing organizations.

claude mcp add --transport http "Polar Sandbox" "https://mcp.polar.sh/mcp/polar-sandbox"


**Cursor**（`.cursor/mcp.json`）：
```json
{
  "mcpServers": {
    "Polar Sandbox": {
      "url": "https://mcp.polar.sh/mcp/polar-sandbox"
    }
  }
}

安装完成后，用户必须：

重启编辑器/CLI
在提示时进行身份验证（将重定向至polar.sh）

身份验证完成后，通过列出组织来验证MCP是否正常工作。

Step 3: Gather Project Context

步骤3：收集项目上下文

Ask the user:

Framework: What framework are you using?
- Next.js (App Router)
- Next.js (Pages Router)
- Express.js
- FastAPI (Python)
- Other
Environment: Start with sandbox or production?
- Sandbox (recommended for new setups)
- Production
Product type: What are you selling?
- Subscription (recurring)
- One-time purchase
- Both

询问用户：

框架：您使用的是什么框架？
- Next.js（App Router）
- Next.js（Pages Router）
- Express.js
- FastAPI（Python）
- 其他
环境：从沙箱环境还是生产环境开始？
- 沙箱环境（推荐用于新设置）
- 生产环境
产品类型：您销售的是什么？
- 订阅（定期付费）
- 一次性购买
- 两者皆有

Step 4: Create Organization (if needed)

步骤4：创建组织（如需要）

Use MCP to check if user has an organization. If not, guide them to create one at:

Sandbox: https://sandbox.polar.sh/start
Production: https://polar.sh/start

使用MCP检查用户是否已有组织。如果没有，引导他们前往以下地址创建：

沙箱环境：https://sandbox.polar.sh/start
生产环境：https://polar.sh/start

Step 5: Create First Product

步骤5：创建首个产品

Use MCP to create a test product. Example for subscription:

Create a product with:
- Name: "Pro Plan"
- Monthly price: $29
- Organization: [user's org]

Store the returned product ID for checkout integration.

使用MCP创建测试产品。订阅产品示例：

创建一个产品，包含：
- 名称："专业计划"
- 月费：29美元
- 组织：[用户的组织]

保存返回的产品ID，用于结账集成。

Step 6: Generate Integration Code

步骤6：生成集成代码

Hand off to the

polar-integration

skill to generate the Checkout, Customer Portal, and Webhooks endpoints for the framework selected in Step 3. That skill has the canonical, framework-agnostic recipes plus per-framework variations.

Before invoking it, make sure the user has these environment variables ready (use whatever loader their framework provides):

bash

POLAR_ACCESS_TOKEN=    # from polar.sh/settings (or sandbox)
POLAR_WEBHOOK_SECRET=  # created in Step 7
POLAR_SERVER=sandbox   # omit or set to "production" when going live

Pass along the product ID from Step 5 so checkout links can be tested in Step 8.

转交至

polar-integration

技能，为步骤3中选择的框架生成结账、客户门户和Webhook端点。该技能包含标准的、与框架无关的方案以及针对各框架的变体。

调用该技能前，确保用户已准备好以下环境变量（使用其框架提供的加载器）：

bash

POLAR_ACCESS_TOKEN=    # 来自polar.sh/settings（或沙箱环境）
POLAR_WEBHOOK_SECRET=  # 在步骤7中创建
POLAR_SERVER=sandbox   # 上线时可省略或设置为"production"

传递步骤5中的产品ID，以便在步骤8中测试结账链接。

Step 7: Set Up Webhooks

步骤7：设置Webhook

Start the local development server.
Start ngrok against the dev server's port:
bash
```
ngrok http <port>
```
Copy the ngrok URL (e.g.,
```
https://abc123.ngrok.io
```
).

Use MCP to create a webhook endpoint, or guide the user to the dashboard:

Sandbox: https://sandbox.polar.sh → Settings → Webhooks
Add endpoint:
```
https://[ngrok-url]/<webhook-path>
```
(use the path from the route generated in Step 6).

Select events:

order.paid

subscription.created

subscription.canceled

Copy the webhook secret into the env var loader from Step 6.

启动本地开发服务器。
针对开发服务器的端口启动ngrok：
bash
```
ngrok http <port>
```
复制ngrok URL（例如：
```
https://abc123.ngrok.io
```
）。

使用MCP创建Webhook端点，或引导用户前往控制面板：

沙箱环境：https://sandbox.polar.sh → 设置 → Webhook
添加端点：
```
https://[ngrok-url]/<webhook-path>
```
（使用步骤6中生成的路由路径）。

选择事件：

order.paid

、

subscription.created

、

subscription.canceled

。

将Webhook密钥复制到步骤6中的环境变量加载器中。

Step 8: Test the Integration

步骤8：测试集成

Start the dev server.
Visit the checkout URL with the product ID from Step 5 (path and query shape come from the route generated in Step 6).
Complete checkout using test card:
```
4242 4242 4242 4242
```
.
Verify the webhook was received in terminal logs.
Check the success page displays correctly.

启动开发服务器。
使用步骤5中的产品ID访问结账URL（路径和查询结构来自步骤6中生成的路由）。
使用测试卡完成结账：
```
4242 4242 4242 4242
```
。
在终端日志中验证Webhook已被接收。
检查成功页面是否正确显示。

Step 9: Next Steps

步骤9：后续步骤

Once basic setup works, suggest:

Add customer portal - Let users manage subscriptions (Recipe 2 in
```
polar-integration
```
).
Link to your auth - Pass
```
externalCustomerId
```
in checkout.
Add benefits - License keys, file downloads, Discord roles.
Go production - Switch
```
POLAR_SERVER
```
from
```
sandbox
```
to
```
production
```
.

基础设置完成后，建议：

添加客户门户 - 允许用户管理订阅（
```
polar-integration
```
中的方案2）。
关联身份验证 - 在结账时传递
```
externalCustomerId
```
。
添加权益 - 许可证密钥、文件下载、Discord角色。
上线生产环境 - 将
```
POLAR_SERVER
```
从
```
sandbox
```
切换为
```
production
```
。