Askell

askell-mcp

Askell の決済・サブスクリプション API 用の MCP サーバーです。

Cursor、Claude Desktop、または任意の MCP クライアントに接続すると、Askell のエンドポイントを見つけたり、顧客・契約・請求情報を確認したり、API を呼び出したりできます。読み取りと書き込みは別々のツールになっているため、変更時にクライアント側で承認 UI を表示できます。

必要条件

• Askell のアカウントとシークレット API キー（Askell ダッシュボードで取得）。パブリックキーは任意です。使用するのは、一時的な支払い方法およびチェックアウトのステータス用エンドポイントのみです
• 次のいずれか：
  • Bun ≥ 1.4.0（bunx 用）、または
  • Releases から入手できるビルド済みバイナリ（Bun は不要）

クイックスタート

本番用とサンドボックス用の両方のキーがある場合は、サーバーエントリを2つ用意することをおすすめします。どちらもツール名は同じですが、クライアントはサーバーキー（askell-prod と askell-sandbox）で区別します。各インスタンスの説明には、接続先の環境が記載されています。

キーは JSON ではなく、Git の管理対象外にした dotenv ファイルに保存してください。.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 のベース URL 専用です。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（分離されたテナント。そのダッシュボードから取得したキーを使用）

1 つのプロセスで環境を切り替えるのではなく、サンドボックス用に 2 つ目の MCP サーバーエントリ（ASKELL_ENV=sandbox）を指定してください。キーはホスト間で使い回せません。Áskell Test Gateway はどちらのホストでも利用できる決済アクワイアラー（偽のカードを使用）であり、サンドボックス API とは異なります。docs.askell.is の公式説明では引き続き Test Gateway が案内されており、サンドボックスホストの記載がない場合があります。

ASKELL_MUTATION_GATE：

• auto（デフォルト） — このリクエストの _meta エンベロープでフォームによるエリシテーションが宣言されている場合のみ、確認フォームを表示します（MCP 2026-07-28）。2025 年代のクライアント（Cursor、大半のホスト）はこのエンベロープを送信しないため、ミューテーションが実行され、クライアント独自の「このツールを許可」UI がゲートになります。
• elicit — 常にエリシテーションフォームを返します。クライアントがフォームに対応できない場合、SDK は呼び出しを拒否します（2026 エンベロープ／レガシーシム経由の 2025 initialize）。
• off — 確認を求めません（評価／信頼済みの自動化用）。

ASKELL_MUTATION_GATE と ASKELL_REQUIRE_MUTATION_APPROVAL の両方が設定されている場合は、ASKELL_MUTATION_GATE が優先されます。

できること

ツール

ツール	説明
askell_list_operations	同梱された OpenAPI オペレーションを検索します
askell_describe_operation	1 つのオペレーションのパラメーターとボディスキーマ
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をご覧ください。