alephant-mcp

Alephant MCP 服务

适用于 Alephant BYO-KEY 的模型上下文协议服务：可在 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+ 版本包含 bin/alephant-mcp.js 垫片，可确保从注册表安装时可靠解析 npm bin。

MCP 客户端配置

Alephant MCP 是本地 stdio 服务。每个凭据范围使用一个服务条目。若要使用多个工作区，请创建多个条目，并为其设置不同的名称和环境变量。

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_PAT 和 ALEPHANT_WORKSPACE_ID，而非 ALEPHANT_VIRTUAL_KEY。

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-… 快捷模板、工具对照表
• Marketplace 提交：请参阅 docs/marketplace-submission.md，了解提交至官方 MCP Registry、Smithery 和 Glama 的说明。

开发

npm install
npm test
npm run build

软件包

以 @alephantai/mcp（alephant-mcp 二进制文件）的形式发布。