alephant-mcp

Alephant MCP サーバー

Alephant BYO-KEY 用の Model Context Protocol サーバーです。Cursor、Claude Desktop、または任意の MCP ホストから FinOps メトリクス、仮想キー、ワークスペースの分析情報を利用できます。

モード

モード	環境変数	ツール
VK	ALEPHANT_VIRTUAL_KEY	コックピットのスコープに応じた使用状況 + 3 つの VK ツール（共通ツールを含めて合計 8 個）
Manager	ALEPHANT_PAT + ALEPHANT_WORKSPACE_ID	ワークスペース全体の管理（共通ツールを含めて合計 27 個）

ALEPHANT_PAT が空でない場合、PAT が優先されます。VK も PAT も設定されていない場合、プロセスはエラーで終了します（モックデータはありません）。

必須（両モード共通）： ALEPHANT_API_BASE_URL
任意： ALEPHANT_RATE_LIMIT_RPM（デフォルトは 60。クライアント側のスロットリングを無効にするには 0 を指定します）

Windows / npx のトラブルシューティング

このリポジトリのルート（alephant-mcp/）から実行する場合： 公開済みパッケージの「スモークテスト」に npx -y @alephantai/mcp を使わないでください。npm はカレントディレクトリをローカルの @alephantai/mcp プロジェクトとして扱い、ルートパッケージの bin を node_modules/.bin にリンクしません。そのため、Windows では 'alephant-mcp' is not recognized（または中国語版 CMD での同等のエラー）が表示されます。

クローンしたリポジトリで開発中は、代わりに次のいずれかを使用してください。

npm start
# or
node .\bin\alephant-mcp.js

エンドユーザーと同じ方法で npx を確認するには、別の任意のディレクトリ（例：親ディレクトリ）から実行します。

cd ..
npx -y @alephantai/mcp

通常のプロジェクトフォルダーから実行する場合（npm install @alephantai/mcp の実行後）は、次の方法も使用できます。

node .\node_modules\@alephantai\mcp\bin\alephant-mcp.js

クローンの外で npx -y @alephantai/mcp が引き続き失敗する場合は、次をお試しください。

npx --yes --package=@alephantai/mcp alephant-mcp

公開済みパッケージ 0.0.2+ には、レジストリからインストールした際に npm の bin を確実に解決するための bin/alephant-mcp.js shim が含まれています。

MCP クライアントの設定

Alephant MCP はローカルの stdio サーバーです。認証情報のスコープごとにサーバーエントリーを 1 つ使用してください。複数のワークスペースがある場合は、名前と環境変数を変えて複数のエントリーを作成してください。

Cursor / Claude Desktop

Virtual Key（読み取り専用 / スコープ指定のコックピット）：

{
  "mcpServers": {
    "alephant": {
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
      }
    }
  }
}

Personal Access Token（マネージャー）：

{
  "mcpServers": {
    "alephant-workspace-a": {
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_PAT": "pat_...",
        "ALEPHANT_WORKSPACE_ID": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

PAT が複数ある場合は、ワークスペースごとに別々の mcpServers エントリーを使用してください。

Codex

~/.codex/config.toml に stdio MCP サーバーを追加します。

[mcp_servers.alephant]
command = "npx"
args = ["-y", "@alephantai/mcp"]
env = {
  ALEPHANT_API_BASE_URL = "https://alephant.io",
  ALEPHANT_VIRTUAL_KEY = "vk-..."
}
startup_timeout_sec = 20
tool_timeout_sec = 120

Manager モードでは、VK の環境変数を次のように置き換えます。

env = {
  ALEPHANT_API_BASE_URL = "https://alephant.io",
  ALEPHANT_PAT = "pat_...",
  ALEPHANT_WORKSPACE_ID = "00000000-0000-0000-0000-000000000000"
}

次のコマンドで確認します。

codex mcp list
codex mcp get alephant

OpenCode

OpenCode の設定で mcp の下にローカル MCP サーバーを追加します。例として opencode.json を示します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "alephant": {
      "type": "local",
      "command": ["npx", "-y", "@alephantai/mcp"],
      "enabled": true,
      "environment": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
      }
    }
  }
}

Manager モードでは、environment 内の ALEPHANT_VIRTUAL_KEY の代わりに ALEPHANT_PAT と ALEPHANT_WORKSPACE_ID を使用します。

Claude Code

CLI を使用して、Alephant をローカル stdio サーバーとして追加します。

claude mcp add-json alephant '{"type":"stdio","command":"npx","args":["-y","@alephantai/mcp"],"env":{"ALEPHANT_API_BASE_URL":"https://alephant.io","ALEPHANT_VIRTUAL_KEY":"vk-..."}}' --scope user
claude mcp list
claude mcp get alephant

プロジェクトで共有する設定には、プロジェクトのルートに .mcp.json を作成します。

{
  "mcpServers": {
    "alephant": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
      }
    }
  }
}

Manager モードでは、VK の環境変数を ALEPHANT_PAT と ALEPHANT_WORKSPACE_ID に置き換えます。

CLI 監査

npx --yes --package=@alephantai/mcp alephant-mcp --audit

• VK： コックピットの scope と usage-summary（請求サイクル）を出力します。
• Manager： ワークスペース ID と GET /api/v1/analytics/overview を出力します。

ツール（概要）

共通（両モード）：check_alephant_connection、get_usage_summary、get_daily_costs、get_cost_by_model、list_available_models
VK 専用：get_my_scope、get_my_budget、get_my_recent_requests
Manager 専用：get_workspace_overview、get_workspace_budget_status、list_virtual_keys、create_virtual_key、update_key_budget、revoke_virtual_key、list_agents、get_agent_analytics、list_members、get_member_analytics、list_departments、get_department_analytics、get_subscription_info、set_budget_policy、get_live_24h、get_usage_timeseries、get_sparklines、diagnose_cost_anomaly、get_executive_dashboard、drill_down_spend、find_idle_resources、compare_entity_periods

get_request_logs は含まれていません（JWT 専用のバックエンドルートです）。

プロンプトとリソース

• cost_audit_report — 両モード
• cost_optimization — Manager モード専用

ドキュメント

• 中文：AI Agent で MCP を使用する方法 — 自然言語での質問例、/alephant-… のショートカットテンプレート、ツール対応表
• マーケットプレイスへの申請：公式 MCP Registry、Smithery、Glama への申請に関する注意事項は、docs/marketplace-submission.md をご覧ください。

開発

npm install
npm test
npm run build

パッケージ

@alephantai/mcp（alephant-mcp バイナリ）として公開されています。