Pricempire

A Model Context Protocol (MCP) server for querying your Pricempire CS2 (Counter-Strike 2) trader portfolio: total value, breakdowns by category, top holdings, cross-marketplace price comparison, and price history.

Built on nt4f04uNd/pricempire, a fork of the official @pricempire/api Node.js client that adds support for the real Trader Portfolio API (/v4/trader/*), which the published npm package does not implement.

This server is read-only / on-demand: it answers questions about your portfolio when asked. It does not run alerts, bots, or schedulers.

What it is useful for

This MCP server is useful when you want an LLM agent to help you inspect your Pricempire portfolio without manually clicking around the UI or exporting data.

Typical use cases:

• check your total portfolio value, invested amount, unrealized P/L, and ROI
• see your most valuable items and how concentrated your portfolio is
• break down value by category such as skins, containers, agents, gloves, and charms
• compare item prices across marketplaces
• inspect historical price data for a specific item or marketplace source
• build portfolio summaries or visualizations in a separate skill layer

How to start using it

The normal flow is:

1. Build this repository and configure your Pricempire API key.
2. Register the server in your MCP client.
3. Ask your agent questions about your portfolio.

Examples of the kinds of prompts this enables:

• "What's my portfolio worth right now?"
• "Show me my top 10 most valuable items."
• "How much of my portfolio is in cases versus skins?"
• "Which items have the biggest unrealized losses?"
• "Visualize my portfolio by category."

Visualization skills

If you want a higher-level presentation layer on top of this MCP server, see pricempire-mcp-cs-tools.

That repository contains CS2-specific skills, prompts, and example visualizations built on top of the tools exposed here. The intended split is:

• pricempire-mcp: data access and portfolio analysis tools
• pricempire-mcp-cs-tools: visualization-oriented skill layer

Prerequisites

• Node.js 18 or newer
• A Pricempire API key with Trader tier access (portfolio value/holdings are a Trader-tier feature; see pricempire.com account settings). Cross-marketplace price lookup tools (get_item_prices, get_price_history) additionally require v3/v4 market data access depending on your plan.

Setup

npm install
cp .env.example .env
# edit .env and set PRICEMPIRE_API_KEY (and optionally DEFAULT_CURRENCY / DEFAULT_SOURCES)
npm run build

.env is git-ignored — never commit real API keys. .env.example documents each variable with placeholder values only.

Environment variables

Variable	Required	Description
PRICEMPIRE_API_KEY	Yes	Your Pricempire API key (UUID v4).
DEFAULT_CURRENCY	No	Default currency code (e.g. USD, EUR). Defaults to USD.
DEFAULT_SOURCES	No	Comma-separated default marketplace sources (e.g. buff163,steam) for get_item_prices. Defaults to buff163,steam.

Portfolios themselves aren't selected via env vars — the account tied to PRICEMPIRE_API_KEY may have multiple named portfolios (e.g. "Main portfolio", "Secondary portfolio"); tools default to all of them combined, or accept an optional portfolio name/slug filter per call.

Running

npm run dev     # run directly from TypeScript source with tsx (auto-reload)
npm run build   # compile to dist/
npm start       # run the compiled server (node dist/index.js)

The server communicates over stdio, per the MCP stdio transport convention.

Registering with an MCP client

Add an entry pointing at the built dist/index.js. Example mcp.json-style configuration:

{
  "mcpServers": {
    "pricempire": {
      "command": "node",
      "args": ["/absolute/path/to/pricempire-mcp/dist/index.js"],
      "env": {
        "PRICEMPIRE_API_KEY": "your-pricempire-api-key",
        "DEFAULT_CURRENCY": "USD",
        "DEFAULT_SOURCES": "buff163,steam"
      }
    }
  }
}

Adjust the path and the exact config file/format for your MCP client (e.g. Copilot CLI, Claude Desktop, etc.).

Quick start checklist

1. Copy .env.example to .env.
2. Set PRICEMPIRE_API_KEY.
3. Run npm install.
4. Run npm run build.
5. Register dist/index.js in your MCP client.
6. Restart or reload the MCP client if needed.
7. Ask a portfolio question such as "Analyze my portfolio."

Available tools

Tool	Description
get_portfolio_value	Total value, 24h change, invested amount, profit/loss and ROI for your trader portfolio(s), per portfolio and combined. Optional portfolio name/slug filter.
list_portfolio_items	Full item list across your portfolio(s) (price, holdings, float, paint seed, stickers, category, avg buy price, unrealized P/L, ROI), sorted by value descending, with optional limit / min_value / portfolio filters.
get_item_prices	Current prices for one or more items by market_hash_name, across marketplaces. Prefers the v4 (paid tier) API, falls back to v3 if unavailable.
get_price_history	Historical price data for a marketplace source over N days.
analyze_portfolio	One-shot structured analysis: total value/invested/P&L/ROI, category breakdown with percentages, top N holdings, unpriced item count. Returns JSON for the calling agent to narrate.

Every tool catches API errors (invalid/missing key, rate limiting, plan restrictions, server errors) and returns a structured error object ({ error: true, kind, message, detail }) instead of throwing, so a calling agent can explain the problem in plain language.

Companion Copilot skill

See skills/pricempire-portfolio/SKILL.md for guidance an LLM agent can use to combine these tools when answering common portfolio questions.

Notes & limitations

• Portfolio tools (get_portfolio_value, list_portfolio_items, analyze_portfolio) use the Pricempire Trader API (/v4/trader/portfolios*), via the nt4f04uNd/pricempire fork depended on in package.json ("@pricempire/api": "github:nt4f04uNd/pricempire#main"). The published npm package does not implement these endpoints — see that fork's README for details on what was added.
• This is currently built on a fork because upstream @pricempire/api does not yet expose the Trader Portfolio API. Upstream tracking issue: pricempire/pricempire#3.
• get_item_prices and get_price_history use the market-wide v3/v4 endpoints from the original package and require separate plan access from the Trader tier; if your key doesn't have that access, these tools return a structured auth/forbidden error rather than crashing.