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

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

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

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.