Askell

askell-mcp

面向 Askell 支付和订阅 API 的 MCP 服务。

将其连接到 Cursor、Claude Desktop 或任何 MCP 客户端，即可发现 Askell 端点、检查客户/合同/账单并调用 API。读取和写入操作是独立工具，因此客户端可以在执行变更时显示自己的审批界面。

要求

• 一个 Askell 账户和密钥 API 密钥（从 Askell 控制面板获取）。公钥为可选项——只有临时支付方式和结账状态端点会用到它
• 满足以下其中一项：
  • Bun ≥ 1.4.0（用于 bunx），或
  • 从 Releases 获取预构建二进制文件（无需 Bun）

快速开始

如果同时有生产环境和沙盒密钥，建议配置两个服务条目。两者的工具名称相同；客户端通过服务密钥（askell-prod 与 askell-sandbox）加以区分。每个实例的说明都包含其所连接的环境。

将密钥放在被 git 忽略的 dotenv 文件中，而不是 JSON 文件中。复制 .env.example：

• .env — 生产环境（ASKELL_ENV=production 和该控制面板的密钥）
• .env.sandbox — 沙盒环境（ASKELL_ENV=sandbox 和该控制面板的密钥）

Bun 不会自动加载 .env.sandbox。--no-env-file 可阻止沙盒进程同时读取恰好位于当前工作目录中的生产环境 .env 文件。

Cursor

项目文件：.cursor/mcp.json。mcp.json.example 展示了该格式。${workspaceFolder} 是包含该 mcp.json 的目录（当文件位于 .cursor/mcp.json 时即为仓库根目录）。在 ~/.cursor/mcp.json 中，请使用绝对路径作为 envFile。

使用 Bun：

{
  "mcpServers": {
    "askell-prod": {
      "command": "bunx",
      "args": ["--no-env-file", "x", "askell-mcp"],
      "envFile": "${workspaceFolder}/.env"
    },
    "askell-sandbox": {
      "command": "bunx",
      "args": ["--no-env-file", "x", "askell-mcp"],
      "envFile": "${workspaceFolder}/.env.sandbox"
    }
  }
}

使用二进制文件（从 Releases 下载 askell-mcp-<os>-<arch>，然后运行 chmod +x）。使用相同的 envFile；二进制文件会读取 Cursor 注入的环境变量：

{
  "mcpServers": {
    "askell-prod": {
      "command": "/absolute/path/to/askell-mcp-linux-x64",
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

保存后重新加载窗口。

Claude Desktop

配置文件：

• Linux：~/.config/Claude/claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

没有 envFile 字段。桌面进程的当前工作目录不是你的仓库，因此相对 .env 路径无法解析。使用 Bun 时，请传入绝对路径的 --env-file：

{
  "mcpServers": {
    "askell-prod": {
      "command": "bunx",
      "args": [
        "--no-env-file",
        "--env-file=/absolute/path/.env",
        "x",
        "askell-mcp"
      ]
    },
    "askell-sandbox": {
      "command": "bunx",
      "args": [
        "--no-env-file",
        "--env-file=/absolute/path/.env.sandbox",
        "x",
        "askell-mcp"
      ]
    }
  }
}

二进制文件不支持 --env-file。请将密钥放入 env（以明文形式保存在该 JSON 文件中）：

{
  "mcpServers": {
    "askell-prod": {
      "command": "/absolute/path/to/askell-mcp-linux-x64",
      "env": {
        "ASKELL_ENV": "production",
        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key",
        "ASKELL_PUBLIC_API_KEY": "your_production_public_api_key_optional"
      }
    }
  }
}

完全退出 Claude Desktop，然后重新打开。仅保存文件还不够。

Claude Code

项目 .mcp.json 会从启动 claude 的进程环境中展开 ${VAR}。它不会加载 dotenv 文件。Desktop 部分中的 Bun --env-file 参数在这里同样适用；如果从仓库启动 claude，相对路径也可以使用。env 中的 ${ASKELL_PRIVATE_API_KEY} 只有在该变量已在该环境中导出时才有效。单独的 .env 文件不会被读取。

配置

变量	必填	默认值	描述
ASKELL_PRIVATE_API_KEY	是*	—	私有 API 密钥（或 ASKELL_SECRET_API_KEY）
ASKELL_PUBLIC_API_KEY	否	—	少数结账／支付端点使用的公钥
ASKELL_ENV	否	production	production | sandbox — 选择官方 API 主机
ASKELL_API_BASE_URL	否	—	仅用于自定义／本地 API 基址。除非与 ASKELL_ENV 匹配，否则不要同时设置
ASKELL_RESPONSE_MAX_BYTES	否	64000	返回给模型的最大响应大小
ASKELL_MUTATION_GATE	否	auto	auto / elicit / off — 见下文
ASKELL_REQUIRE_MUTATION_APPROVAL	否	—	已弃用的别名：true→elicit，false→off

ASKELL_ENV 会选择一个稳定的主机（v1/v2 接口相同）：

• production — https://askell.is/api
• sandbox — https://sandbox.askell.is/api（隔离租户；密钥从该控制面板获取）

请为 sandbox 单独配置一个 MCP 服务条目（ASKELL_ENV=sandbox），而不要在一个进程中切换环境变量。密钥无法跨主机使用。Áskell Test Gateway 是两种主机上都可用的支付收单方（使用虚拟卡），与 sandbox API 并非一回事。docs.askell.is 上的官方文档仍介绍 Test Gateway，且可能未提及 sandbox 主机。

ASKELL_MUTATION_GATE：

• auto（默认） — 仅当_此请求_的 _meta 信封声明支持表单征询（MCP 2026-07-28）时，才显示确认表单。2025 年的客户端（Cursor 和大多数宿主）不会发送该信封，因此会执行变更操作，审批关卡则由它们自己的“允许此工具”界面承担。
• elicit — 始终返回征询表单。如果客户端无法完成该表单（2026 信封／通过旧版兼容层进行 2025 初始化），SDK 会拒绝调用。
• off — 从不询问（评估／受信任的自动化）。

如果同时设置了 ASKELL_MUTATION_GATE 和 ASKELL_REQUIRE_MUTATION_APPROVAL，则以 ASKELL_MUTATION_GATE 为准。

可以做什么

工具

工具	描述
askell_list_operations	搜索内置的 OpenAPI 操作
askell_describe_operation	查看某项操作的参数和请求体架构
askell_call	对任意 v1/v2 端点执行 GET/HEAD
askell_mutate	对任意 v1/v2 端点执行 POST/PUT/PATCH/DELETE
askell_paginate_all	遍历分页列表端点
askell_customer_overview	v1 客户及订阅概览
askell_contract_overview	v2 订阅合约及账单运行概览
askell_billing_run_triage	v2 账单运行（可选包含合约）
askell_list_webhooks	列出已配置的 Webhook（hmac_secret 已隐藏）

资源

URI	内容
askell://spec/v1	OpenAPI v1
askell://spec/v2	OpenAPI v2
askell://docs/webhook-events	Webhook 事件参考

文档：docs.askell.is · OpenAPI：v1 · v2

许可证

MIT

贡献

有关本地开发、测试和发布，请参阅 CONTRIBUTING.md。