MCP Server

What it is

@bearlumen/mcp-server is a Model Context Protocol server: a small program your MCP client launches over stdio. It wraps the Bear Lumen API and offers 15 read-only tools across costs, margins, insights, usage, and attribution. Everything is scoped to the account that owns the configured API key, and nothing it exposes can modify your data.

Prerequisites

• Node.js 18 or newer.
• A Bear Lumen API key. Create one at app.bearlumen.com/settings/api-keys.

Configuration

The server reads BEAR_LUMEN_API_KEY (required) and, optionally, BEAR_LUMEN_BASE_URL to point at a non-production host.

Claude Desktop

Add this to claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "bear-lumen": {
      "command": "npx",
      "args": ["-y", "@bearlumen/mcp-server"],
      "env": {
        "BEAR_LUMEN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Use the same JSON block in ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).

Claude Code

claude mcp add bear-lumen \
  --env BEAR_LUMEN_API_KEY=your-api-key-here \
  -- npx -y @bearlumen/mcp-server

The tools

Once connected, the agent can call any of these. Every date-windowed tool accepts start_date / end_date as ISO YYYY-MM-DD and defaults to the trailing 30 days when omitted.

• ping — verify the key and connectivity.
• get_cost_summary — total spend now vs the previous period.
• get_cost_trend — cost over time.
• get_costs_by_model, get_costs_by_provider, get_costs_by_feature, get_costs_by_end_user — cost broken down by that axis.
• get_costs_by_dimension — cost grouped by any axis, including agent, workflow, or a custom metadata key.
• get_margin_summary, get_margins_by_end_user, get_margin_trend — revenue vs cost and profitability.
• get_insights_summary — a digest of top movers and outliers.
• get_usage_summary, get_usage_events — usage volume and raw events.
• list_dimensions — the custom dimensions you can group by.

Teaching your agent to use it

The package ships a SKILL.mdfile that documents when and how to use each tool: the date conventions, the difference between your own user IDs and Bear Lumen's internal IDs, how a nullcost differs from a real zero, and worked examples such as "find our unprofitable customers." Give it to your agent as a skill or in its system prompt for the best results.

Prefer a terminal?

The Bear Lumen CLI exposes the same query surface as command-line commands, with a one-to-one mapping to these tools.