Skip to main content
Glama
pricempire-mcp

pricempire-mcp

by nt4f04uNd

Pricempire MCP Server

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 on-demand: it can both inspect Pricempire data and, for the Trader API surface exposed by the installed JS client fork, perform write operations such as creating portfolios, managing transactions, and maintaining price alerts. It does not run alerts, bots, or schedulers by itself.

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

  • create/update/delete trader portfolios and transactions

  • create/update/delete price alerts

  • access trader insights, trends, and raw v3/v4 endpoints

  • build portfolio summaries or visualizations in a separate skill layer

Related MCP server: Questrade MCP Server

Trader transaction notes

The live Pricempire Trader API has two quirks that matter for transaction writes:

  • asset_id alone is not reliable for item-specific transactions. For accurate imports, prefer passing asset_item_id as well.

  • transaction prices are effectively expected in cents, not floating-point USD values. For example, 0.70 USD should be sent as 70.

Because of that, trader_add_transaction in this MCP server behaves defensively:

  • if you provide asset_item_id, it creates the transaction and immediately rebinds it to the concrete item with a follow-up update

  • if you omit asset_item_id and provide a single market_hash_name, it returns a ready-to-open pricempire.com/api-data/... lookup URL

  • if you omit asset_item_id and provide multiple market_hash_names, it returns a one-shot browser-console script that resolves all required IDs in one run

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 family

Description

get_portfolio_value, list_portfolio_items, get_item_prices, get_price_history, analyze_portfolio

Opinionated high-level tools for portfolio analysis and visualization workflows.

v3_*

Raw parity tools for the JS client's v3 methods: all items, basic/advanced data, inventories, structured items, item IDs, and self inventory.

v4_*

Raw parity tools for the JS client's paid-tier v4 methods: prices, item metas, item catalog, and item images.

trader_*

Raw parity tools for the JS client's v4.trader methods: portfolios, transactions, alerts, insights, trends, signals, exports, and trader-tier prices.

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.

trader_add_transaction expectations

For reliable use of trader_add_transaction, pass:

  • price in cents, for example 70 for 0.70 USD

  • asset_item_id whenever you already know the exact item variant

If asset_item_id is missing, the tool returns a structured helper payload instead of silently creating a likely mis-bound transaction.

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#codex/trader-portfolio-api"). The published npm package does not implement these endpoints — see that fork's README for details on what was added.

  • The MCP server also exposes raw-parity tools for the installed fork's v3, v4, and v4.trader method surface in addition to the higher-level analysis helpers documented above.

  • 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.

Available Tools

5 tools
analyze_portfolioAnalyze portfolioA

Fetch your Pricempire trader portfolio(s) once and return a structured analysis: total value, invested amount, profit/loss and ROI, a breakdown by item category (skin/container/glove/agent/charm/sticker) with subtotals and percentages, the top N most valuable holdings, and how many items had no current price match. Output is structured JSON, not prose, so the calling agent can turn it into a narrative for the user.

Inputs: topN, portfolio.

get_item_pricesGet item prices across marketplacesA

Get current prices for one or more CS2 items (by market_hash_name) across marketplaces. Tries the Pricempire v4 API first (paid tier, richer per-source pricing); if that endpoint is unavailable (e.g. plan restriction) it falls back to the free v3 getAllItems endpoint. The response indicates which API tier was used, or reports the failure clearly.

Inputs: market_hash_names (required), sources, currency.

get_portfolio_valueGet portfolio valueA

Get the total current value of your Pricempire trader portfolio(s): value, 24h change, item count, total invested, profit/loss, and ROI, per portfolio and combined. Uses the Pricempire Trader API (v4/trader/portfolios), tied to the account owning the configured API key. Requires a Pricempire trader-tier subscription.

Inputs: portfolio.

get_price_historyGet item price historyA

Get historical price data for a given marketplace source over a number of days (Pricempire v3 getPriceHistories). Useful for "show me price history for X" style questions about market trends.

Inputs: days, appId, source, currency.

list_portfolio_itemsList portfolio itemsA

List the items held in your Pricempire trader portfolio(s), with per-item details (current price, holdings/quantity, float, paint seed, stickers, category, avg buy price, unrealized P/L, ROI), sorted by current value descending. Supports optional limit and min_value filters, and an optional portfolio name/slug filter for accounts with multiple portfolios. Useful for "what are my most valuable items" style questions.

Inputs: limit, min_value, portfolio.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct operation: full portfolio analysis, item prices, portfolio value, price history, and portfolio item listing. There is no overlap in their purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., analyze_portfolio, get_item_prices), making it predictable and easy to understand.

    Tool Count5/5

    With 5 tools, the server covers the core functionalities (pricing, portfolio value, history, listing, analysis) without being over- or under-scoped.

    Completeness4/5

    The tool set provides essential read operations for CS2 item pricing and portfolio management. Minor gaps exist, such as no global item search or filter, but the analysis tool compensates by summarizing top holdings.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      An unofficial MCP server that integrates with the Questrade API to provide access to trading accounts, market data, and portfolio information. It enables users to view balances, track positions, search symbols, and analyze market trends through natural language.
      9
      25 npm
      6
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that turns Interactive Brokers into a question-answering portfolio analyst.
      4
      -