check-balance 0.1.0

一键查询当前 AI 服务的账户余额，支持 14 个主流 AI 提供商

check-balance

中文文档

One-click balance checker for your AI API services. Supports 14 mainstream AI providers with automatic detection. Works as an MCP server or standalone CLI.

Features

• MCP Server — Integrates with opencode, Claude Code, Cursor, Claude Desktop
• CLI Tool — Run check-balance in any terminal
• Auto-detection — Reads opencode config and environment variables
• 14 Providers — China (￥) and International ($) regions
• Cross-platform — Linux, macOS, Windows (WSL supported)
• Zero config — Just set your API keys and go

Supported Providers

China Region (￥)

Provider	API Key Env	Balance API	Status
DeepSeek	DEEPSEEK_API_KEY	GET /user/balance	✅ Direct query
Moonshot / Kimi	MOONSHOT_API_KEY	GET /v1/users/me/balance	✅ Direct query
MiniMax	MINIMAX_API_KEY	GET /v1/token_plan/remains	✅ Direct query
StepFun	STEP_API_KEY	GET /v1/accounts	✅ Direct query
Zhipu / GLM	ZHIPU_API_KEY	Quota API	~ Quota info
DashScope / Qwen	DASHSCOPE_API_KEY	—	⚠️ Console only
Baichuan	BAICHUAN_API_KEY	—	⚠️ Console only

International Region ($)

Provider	API Key Env	Balance API	Status
OpenAI	OPENAI_API_KEY	Usage/Cost API	~ Usage + cost
Anthropic / Claude	ANTHROPIC_API_KEY	Admin Key Cost API	~ Usage + cost
xAI / Grok	XAI_API_KEY	Balance API	✅ Direct query
Together AI	TOGETHER_API_KEY	Usage API	~ Usage + cost
Mistral	MISTRAL_API_KEY	—	⚠️ Console only
Groq	GROQ_API_KEY	—	⚠️ Console only
Cohere	COHERE_API_KEY	—	⚠️ Console only

Note: Cursor subscription balance is not supported as Cursor uses its own proxy and does not expose API keys.

Installation

pip install check-balance

Usage

As CLI

check-balance
# or
python -m check_balance

As MCP Server

opencode

Add to your opencode.json:

{
  "mcp": {
    "check-balance": {
      "type": "local",
      "command": ["python", "-m", "check_balance.mcp_server"],
      "enabled": true
    }
  }
}

Then type /balance in opencode or ask "check my AI balance".

Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "check-balance": {
      "command": "python",
      "args": ["-m", "check_balance.mcp_server"]
    }
  }
}

Or add to ~/.claude/mcp.json for global access.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "check-balance": {
      "command": "python",
      "args": ["-m", "check_balance.mcp_server"]
    }
  }
}

Or add to ~/.cursor/mcp.json for global access.

Claude Desktop

Edit claude_desktop_config.json:

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

{
  "mcpServers": {
    "check-balance": {
      "command": "python",
      "args": ["-m", "check_balance.mcp_server"]
    }
  }
}

How It Works

1. Auto-detection — Reads opencode.json to identify your current model/provider, then scans environment variables for all configured API keys
2. Balance query — Calls each provider's balance/usage API
3. Formatted output — Shows results with ￥ (China) or $ (International) currency

Output Example

AI 服务余额查询
==================================================
 * DeepSeek (中国)
     余额: ￥ 142.50

   Moonshot (中国)
     余额: ￥ 3.00

   OpenAI (海外)
     OpenAI 未开放余额查询 API，近 30 天用量: $ 18.32
     控制台: https://platform.openai.com/usage

   Mistral (海外)
     未开放余额查询 API
     控制台: https://console.mistral.ai/usage

* 标记为当前使用的服务

Development

git clone https://github.com/hanmumuHL/check_balance.git
cd check_balance
pip install -e ".[dev]"
pytest

License

MIT