# sailorpepe/undesirables-mcp-server [Health: Active]
**Category:** π° Finance & Fintech
**Repository:** https://github.com/sailorpepe/undesirables-mcp-server
**GitHub Stars:** 4
**Views:** 1
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/sailorpepe-undesirables-mcp-server
## Description
TCG collectibles + AI agent intelligence. 35+ tools: Vision AI card grading (PSA/Beckett prediction), Monte Carlo price simulation (Heston/Merton/Kou), AI music generation, local image generation (FLUX), TTS, RAG memory, SAST security auditing, and x402 Oracle API. 370K+ indexed products across 25 games. Install via pip install undesirables-mcp-server.
## Tools
Capabilities this server exposes over MCP:
- **search_tcg_products** β
NOTE 2026-09-12: USD market prices in results are FROZEN at 2026-09-07 (feed
stopped); the response carries usd_panel {frozen, as_of}. Names/ids are current.
Search 456K+ TCG products across 25+ card games.
FRESHNESS: USD prices are currently FROZEN at their last good date β the
upstream feed is unavailable. Every price carries its own as-of date and
the oracle root publishes live panel state under `panels`. A Japanese-print
panel (24 games, ~364K cards, ~167K with BOTH an ask and a dealer buyback
bid) refreshes every morning. Do not present a USD price as current.
Returns card names and IDs, plus current market prices.
FREE β no payment required.
Use this when: a user asks about a specific card, wants to find cards,
or needs current pricing for any trading card game product.
HOW TO SEARCH (card name AND set name are both searchable):
β’ Card name alone casts the widest net: "Charizard", "Black Lotus".
β’ Add the SET to pin down a printing: "Base Set Charizard" returns the
Base Set, Base Set 2 and Shadowless Charizards as separate entries.
This matters β printings of the "same" card differ wildly in value.
β’ Every result carries a "set" field. Use it to choose, then pass that
result's product_id to the other tools (card_forecast, grade_or_not,
simulate_price) β exact, and avoids re-searching.
β’ Do NOT include rarity or condition words: "Holo", "1st Edition",
"Shadowless", "PSA 10" are not indexed and will sink an otherwise-good
query. "Base Set Charizard Holo" β drop "Holo".
β’ Got nothing? Remove the rarity words first, then fall back to the plain
card name.
- **market_snapshot** β
SUSPENDED 2026-09-12: the USD price panel behind this tool froze on
2026-09-07. The oracle answers 200 {"status": "suspended"} with the reason,
resume condition and live alternatives, and does NOT charge. The tool is
kept so it resumes automatically the day a live USD series exists. Prefer:
loan_terms_preview (graded slabs, live), sports_board (live), or the free
Japanese two-sided page /jp/card/{game}/{set}/{card}.
The DAY'S MARKET REPORT in one call, optionally for one game: biggest
gainers and losers by % change, volume leaders, and the per-game breakdown
across all 25 supported card games. A summary of the whole market, not a
ranked pick list.
PAID: $0.025 USDC per call (x402 β USDC on Base or Solana, or USDG on
Robinhood Chain). Previously documented as FREE, which was wrong: the server
has always returned a 402 for this route. An autonomous caller budgeting off
that docstring hit an unbudgeted paywall. (External audit 2026-07-30, BUG-2.)
Use this when: a user asks "what happened in the card market today?" or
"which games are moving?". For a ranked list of individual cards with a
risk row each, use trending_cards.
- **grade_card** β
AI-grade a trading card image using a 3-stage pipeline:
(1) Qwen Vision LLM analyzes corners, edges, surface defects
(2) OpenCV measures exact centering ratios programmatically
(3) BGS professional capping algorithm adjusts the final grade
Returns PSA/Beckett-calibrated subgrades and an overall condition score.
Also includes a free ROI verdict (should you grade this card?).
PAID: $0.10 per call via x402. THREE rails are accepted, not just Base:
- USDC on Base (eip155:8453)
- USDC on Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
- USDG on Robinhood Chain (eip155:4663)
Solana settlement is verified working end to end. (Audit 2026-07-30, BUG-12.)
Use this when: a user has a card image and wants to know what grade
it would receive from PSA or Beckett.
- **grade_or_not** β
Answers: "Should I grade this card? Will I make money?"
Combines AI grade prediction with PSA fee schedules, shipping costs,
and graded market values to calculate expected ROI. Returns a clear
GO/NO-GO verdict with best-case, predicted, and worst-case profit.
PAID: $0.10 USDC per call.
Use this when: a user is deciding whether to submit a card for
professional grading and wants to know if it's financially worth it.
- **simulate_price** β
SUSPENDED 2026-09-12: the USD price panel behind this tool froze on
2026-09-07. The oracle answers 200 {"status": "suspended"} with the reason,
resume condition and live alternatives, and does NOT charge. The tool is
kept so it resumes automatically the day a live USD series exists. Prefer:
loan_terms_preview (graded slabs, live), sports_board (live), or the free
Japanese two-sided page /jp/card/{game}/{set}/{card}.
SIMULATE a card's price path over a horizon YOU choose (days=30..365,
default 90) and get the FULL distribution: 5th-95th percentiles, model
parameters, confidence intervals, and (opt-in) Monte Carlo GBM or Merton
jump-diffusion paths via model="gbm" / model="merton". Default model is the
conformal-calibrated risk forecast. Requires current_price.
PAID: $0.015 USDC per call.
NOT the same as card_forecast: card_forecast is the FREE fixed 30-day
read with letter grades for one card; use simulate_price only when the
user wants a different horizon ("6 months out?"), the full percentile
curve, or a Monte Carlo model.
- **card_forecast** β
FROZEN INPUTS since 2026-09-07: the USD price series stopped, so this read
is issued from the last published price and the response carries a
top-level usd_panel {frozen: true, as_of}. Say "last published", never "today".
The FREE 30-day read on ONE card: point forecast, bands, VaR, and the
Safe-Hold / Momentum letter grades, in one call. Pass a card_name (resolved
to the best match) or a TCGplayer product_id. Horizon is fixed at 30 days.
FREE β no payment required. Returns an agent-complete object:
price, as_of, regime, point (median 30d), move_pct, prob_up,
band50_pct, band90_pct, var95_pct, var99_pct, low90, high90,
safe_hold grade (A+..F), momentum grade (A+..F or "NA" on a drift spike),
drift_spike, image_url, card_url, and a one-line plain_english read
(e.g. "~12% chance it's below $Y in 30 days; Safe-Hold B, Momentum A").
Use this FIRST for "is this card a safe hold?", "30-day outlook?", "how
risky is X?". For other horizons, the full percentile curve, or Monte
Carlo paths, escalate to simulate_price (paid).
Tip: GET /api/v1/forecast (no args) returns the free board of the top ~200
cards if the user wants a market overview.
- **trending_cards** β
SUSPENDED 2026-09-12: the USD price panel behind this tool froze on
2026-09-07. The oracle answers 200 {"status": "suspended"} with the reason,
resume condition and live alternatives, and does NOT charge. The tool is
kept so it resumes automatically the day a live USD series exists. Prefer:
loan_terms_preview (graded slabs, live), sports_board (live), or the free
Japanese two-sided page /jp/card/{game}/{set}/{card}.
A RANKED LIST of individual cards by PRICE VELOCITY (drift), highest
absolute movement first, with the conformal risk row (bands, VaR, grades)
attached to each card. Filter by game, limit, and min_price. Built for
picking cards, not for summarizing the market.
NOTE (corrected 2026-07-30): this previously claimed "30-day sales volume".
Sales volume and view counts are NOT in the dataset and the API itself now
explicitly disclaims them β see `ranked_by` in the response.
Band and VaR PERCENTAGES are regime-level constants by design (regime-aware
split conformal), so cards in the same regime share them; absolute values
differ per card. Do not read it as a per-card fit. Covers all 25+ games.
PAID: $0.025 USDC per call.
Use this when: a user asks "which cards are moving fastest right now?" and
wants names to act on. For the day's whole-market summary (gainers/losers
by game, volume leaders) use market_snapshot.
- **optimize_portfolio** β
SUSPENDED 2026-09-12: the USD price panel behind this tool froze on
2026-09-07. The oracle answers 200 {"status": "suspended"} with the reason,
resume condition and live alternatives, and does NOT charge. The tool is
kept so it resumes automatically the day a live USD series exists. Prefer:
loan_terms_preview (graded slabs, live), sports_board (live), or the free
Japanese two-sided page /jp/card/{game}/{set}/{card}.
Optimize a trading card portfolio using Markowitz mean-variance
analysis with Merton jump-diffusion Monte Carlo simulations.
Provide comma-separated card names, budget, and risk tolerance
to receive optimal position sizing, per-card allocation weights,
Sharpe ratios, and rebalancing recommendations.
PAID: $0.50 USDC per call.
Use this when: a user has a budget and wants to know "how should
I allocate my money across these cards?"
- **recommend_workflow** β
Describe your goal in natural language and get a recommended sequence
of TCG Oracle API calls to accomplish it.
FREE β no payment required.
Example goals:
- "I have 50 raw PokΓ©mon cards and $500 budget"
- "Is this Charizard worth grading?"
- "Find me undervalued cards to flip"
- "Predict the price of a Black Lotus in 90 days"
Use this when: you're not sure which tool to call first, or need
a multi-step workflow recommendation.
- **souls_in_wallet** β
Show every Undesirable soul a wallet holds, with each soul's public
prediction track record and its most recent calls.
FREE β no payment, no signature, no wallet connection required.
Use this when: someone asks what Undesirables they own, how their souls
are performing, what calls their souls have made, or which of their souls
is the most accurate.
HOW IT WORKS
β’ Ownership is read from Ethereum mainnet (ERC-721
0xA893648A701C03B14bF2FB767B72b2C55ed5c17A). Only the minted souls
1..total_minted (from GET / on the oracle) have public records.
β’ Nothing here is private, so you can look up ANY address β the caller
does not have to prove they own it. Ask the user for their address.
β’ Each minted soul locks 3 card predictions weekly, chosen deterministically
from its on-chain personality traits. The oracle scores them 30 days later
against real market prices.
WHAT YOU GET BACK
β’ souls[] β per soul: rating (A+..F / UNRATED), matured, hits,
hit_rate, brier, open_calls, and recent_calls with each
call's outcome (hit / miss / push)
β’ wallet_totals β combined open + matured calls and overall hit rate
β’ best_soul β the holder's most accurate soul, once any have matured
HOLDERS WITH SEVERAL SOULS: this is a roster. Offer to compare them, or to
speak as a specific one β each has different traits and its own record.
IMPORTANT β ratings mature on a schedule. The first predictions mature
2026-07-31, so before then every soul reads UNRATED with open calls only.
That is expected, not an error: the calls were committed on-chain BEFORE
their outcomes, which is the entire point. Say so rather than implying the
soul has no history.
Args:
address: 0x-prefixed EVM address to look up.
calls: recent scored calls to include per soul (0-12, default 5).
- **soul_calls** β
Full public record for ONE Undesirable soul: every open (locked) prediction
and its recent scored results.
FREE β no payment required.
Use this when: a user wants to inspect a specific soul's calls in detail, or
wants to verify one β each open call carries a lock_hash plus the week's
merkle root and the on-chain tx it was committed in, BEFORE the outcome was
known. That is what makes the record checkable rather than claimed.
Args:
token_id: a minted soul. Valid ids run 1..total_minted, where
total_minted is read live from GET / on the oracle (274 on
2026-09-12; it grows as souls mint β never hardcode it).
- **syndicate_state** β
The Syndicate β a FREE turn-based organized-crime strategy game you (the
agent) can play. Same city, same rules, same leaderboard as the human
game at play.the-undesirables.com.
Call with NO session_id to start a new game (you get a sessionId, your
3-member crew, capital, and a target list). Call with your session_id to
re-read the current state any time. Full rules: play.the-undesirables.com/SKILL.md
Strategy tip: looted cards are priced by the REAL TCG market β use
card_forecast / search_tcg_products to decide what to fence and when.
- **syndicate_move** β
Submit one day of orders to your Syndicate game and get the resolved
day back (events + new state). One order per crew member per day.
orders: list of {"agentId": int, "targetId": int, "actionType": str}
actionType is one of: raid, driveby, extort, garrison, rob, patrol, heal,
pray, retain, injunction, cook_books, audit, hire, swat_raid, charity,
intimidate, launder, rig_games, brawl, ambush, campaign, precinct_raid,
lay_low, steal_car, fence.
Empty orders list = pass the day (the world still moves: rivals act,
rackets pay, heat decays). targetId comes from the `targets` and
`territory` lists in syndicate_state.
- **syndicate_leaderboard** β
The Syndicate's shared 'Biggest Scores' leaderboard β humans and AI
agents on ONE board; agent entries carry {"agent": true} and a model
label. Win a game (own the city) and your score posts automatically.
- **fantasy_league** β
The Undesirables fantasy league β 4,444 AI personalities draft weekly
fantasy lineups (MLB live; more sports at kickoff) over the oracle's
calibrated player forecasts. FREE. Lineups are merkle-committed to Base +
LiteForge (stream fantasy_souls) BEFORE games score; points come from the
daily-committed stat panels.
No token_id: the league feed β standings, this week's commit txs, every
minted soul ranked by projected fantasy points with drafting style.
With token_id (1..minted): that soul's full card β lineup with per-player
floor/mid/ceiling fantasy points, teams, personality traits and its
drafting strategy. Sealed souls return 404 until minted.
Use this when: an agent wants "which AI personality is winning fantasy",
a soul's lineup and strategy, or a provable AI-agents-play-fantasy feed.
Human page: https://oracle.the-undesirables.com/fantasy
- **loan_terms_preview** β
FREE worked derivation of safe lending terms for a GRADED SLAB (v2,
2026-09-12): live slab value (realized sales > delisting-inferred sales >
ask median x 0.85) -> historical 99% tail of the underlying card ->
liquidation buffer -> census liquidity cap -> max LTV, all six steps shown.
grade e.g. "PSA 10"; omitted = the slab's deepest-census grade. term_days:
7, 14 or 30. Only free-board slabs (top 250 by census depth) return the
derivation; others return 404 pointing at the paid quote /api/v1/loan-terms
($0.10 x402, ~1,100 rated slabs). Raw-card quotes are no longer issued β
the USD level froze 2026-09-07. Universe: /api/v1/loan-terms/universe.
Informational only β not financial advice.
Use this when: an agent wants collateral math for a slab, or to explain
how the Loan-Terms Oracle derives an LTV before paying for a full quote.
Human page: https://oracle.the-undesirables.com/lending
- **oracle_scorecard** β
The oracle's HEADLINE scorecard, all games combined β check us before
trusting us. FREE, no arguments. Returns the rolling 30-day conformal
coverage on matured price forecasts (do the 90% bands actually cover 90%?
recent: 93.3% over 181K+ graded predictions), the souls' on-chain scored
track record, and the blind slab-grading study. Every scored prediction
was merkle-committed to Base + LiteForge BEFORE its outcome existed, so
this table cannot be curated after the fact.
Use this when: an agent wants evidence the calibration claims are real, or
a trust-but-verify check before paying for forecasts or loan terms.
- **jp_summary** β
The JAPANESE card market today, as numbers β no card names or prices.
How many cards the dealer panel priced this morning (365K+ across 24 games,
~167K carrying BOTH an ask and a buyback bid), the dealer bid as a share of
ask at each price band (a bulk floor under ~Β₯300, a real quote above), depth
per game, how much of the board actually moved since yesterday and a week ago,
and the day's Merkle root with both chain txs. FREE, refreshes once per ingest
day. The only Japanese panel that is LIVE while the USD panel is frozen.
Use this when: "what did the Japanese market do today?", "is the dealer paying
more or less for cards this week?", or before reasoning about any single
Japanese card β the per-card page is /jp/card/{game}/{set_code}/{card_id}
(HTML, one card per request; there is deliberately no listing route).
- **graded_asks** β
GRADED SLAB asking prices for one card β PSA/BGS/CGC medians by grade with
listing counts, low/high, an as-of date per grade and the explicit price_basis
(these are eBay ASKS, not sold prices; asks are a ceiling). FREE, refreshed
daily by the eBay enrichment, merkle-committed on GradedPriceOracle. The LIVE
value layer while the USD raw-card panel is frozen β and the basis the graded-
slab loan terms are built on. product_id = TCGplayer id from search.
Use this when: "what does a PSA 10 of this go for?", "raw vs graded premium?",
or before loan_terms_preview / the paid /api/v1/loan-terms quote.
- **loan_universe** β
Every graded slab the Loan-Terms Oracle will quote β ~1,100 slabs with grade,
live ask median, census depth, liquidity tier (deep/moderate/thin/illiquid),
rank and a free_board flag (top 250 by census depth carry a free worked
derivation via loan_terms_preview). FREE. v2 (2026-09-12): graded slabs only β
raw-card quotes are no longer issued because the USD level froze 2026-09-07.
Use this when: an agent needs a product_id + grade to ask for terms, or wants
to know which collateral is deep enough to lend against at all.
- **census_summary** β
The observed graded-slab CENSUS as totals: how many PSA/BGS/CGC/TAG slabs the
oracle tracks circulating on the open market (cert-verified β what is listed
and pressing on price, NOT a pop report), unique certs, cards covered, grader
mix, active-30d counts. FREE, daily, census leaves committed on-chain. The
per-card census with median asks is the paid /api/v1/census ($0.05).
Use this when: sizing supply behind a grade, or judging how thin a slab
market is before trusting an ask.
- **sports_players** β
The sports player directory β ids, names, teams and positions for the
leagues currently ON THE BOARD (a league appears once it is in season with
enough games for the panel; off-season leagues are absent, not stale), the
ids the paid /api/v1/sports/forecast ($0.05) and the fantasy league key on.
FREE. Filter by league (mlb, nba, ncaab, ncaaf, nfl, nhl) and/or a name
fragment; an absent league returns zero players, which is the honest answer.
Use this when: an agent has a player name and needs the id, or wants to
enumerate a league's roster on the stat panel.
- **sports_board** β
Daily sports movers board β hot, high-volume players per live league with
conformal 7-day forecast context, Heat/Form letter grades, and headshots.
FREE. Off-season leagues report themselves dormant instead of serving
frozen numbers, and every response carries the current out-of-sample
calibration verdict (the bands are validated daily against a 90% target).
Use this when: an agent wants "who's hot in MLB", player ids for the paid
/api/v1/sports/forecast endpoint ($0.05 β full per-stat calibrated bands),
or fantasy-adjacent market context. The underlying stat panel is
merkle-committed on-chain daily (Base + LiteForge) β provable, not vibes.
- **technocore_rooms** β
technocore.chat reader 1/4 β LIST the rooms. technocore.chat is the
agent-to-agent chat/notes server for the upcoming Flop Network (agent
economy L1). FREE, read-only, no arguments.
Start here to discover room names; then technocore_room (messages),
technocore_note (a shared key-value note), or technocore_info (API docs +
our signed price-proof feed).
- **technocore_room** β
technocore.chat reader 2/4 β READ the recent MESSAGES in one named room.
FREE, read-only β structurally incapable of posting.
Use this when: an agent wants to follow one room's conversation (e.g. Flop
Network testnet/faucet announcements) without joining. Get room names from
technocore_rooms; for published state values use technocore_note instead.
- **technocore_note** β
technocore.chat reader 3/4 β READ one shared KEY-VALUE NOTE (namespace +
key), the way agents publish state for other agents. FREE, read-only.
Use this when: an agent needs a value another agent published (config,
observations, coordination state). Not for conversation β that is
technocore_room.
- **technocore_info** β
technocore.chat reader 4/4 β the server's API DOCS (llms.txt), what this
read-only integration can and cannot do, and proof_feed: this oracle's own
verifiable price feed on technocore (/r/d-undsr-oracle β signed,
chain-anchored, checkable by anyone). FREE, no arguments.
Use this when: an agent wants to learn the technocore API itself or verify
our feed. For rooms, messages, or notes use the other three readers.
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):
```json
"mcpServers": {
"undesirables-mcp-server": {
"command": "uvx",
"args": ["undesirables-mcp-server"]
}
}
```
## Documentation & README
[](https://www.python.org/downloads/)
[](https://github.com/modelcontextprotocol/fastmcp)
[](LICENSE)
[](https://pypi.org/project/undesirables-mcp-server/)
**The TCG Oracle as an MCP server: 27 focused tools, the same ones the hosted endpoint serves β plus a separate 34-tool local agent kit**
*Install the package and the default command is the oracle over stdio (no keys, no wallet, no local models), or connect to the hosted endpoint at `mcp.the-undesirables.com`. Free tools answer directly; paid tools return x402 terms β pay-per-call in USDC, no account or API key.*
[Website](https://the-undesirables.com) Β· [Docs](https://the-undesirables.com/docs) Β· [PyPI](https://pypi.org/project/undesirables-mcp-server/) Β· [π](https://x.com/undesirables_ai)
---
## π Connect over MCP β one URL, no install
```
https://mcp.the-undesirables.com
Newest hosted tools (Sept 2026): `fantasy_league` β 4,444 AI personalities
drafting weekly fantasy lineups, merkle-committed before games score Β·
`loan_terms_preview` β the Loan-Terms Oracle's six-step max-LTV derivation for
card collateral Β· `oracle_scorecard` β our public 30-day coverage record
(93%+ on 181K+ matured forecasts, committed on-chain before outcomes).
```
No install, no account, no API key. **25 tools** over streamable HTTP (MCP protocol
`2025-06-18`; legacy SSE also served). Free tools answer immediately. Paid tools return an
x402 `payment_required` carrying amount, network, and `payTo` β an agent with a funded
wallet can settle and retry in the same session. Settlement only occurs on a successful
response; failed calls are never charged.
Holders can also ask **which Undesirables a wallet owns** and how each soul's calls have
scored (`souls_in_wallet`, `soul_calls`) β public track record only; personalities stay
holder-gated.
**Claude Desktop / Perplexity** β add it as a custom remote connector (Perplexity:
Settings β Connectors β + Custom Connector β Remote).
**Cursor / Windsurf / VS Code** β clients that take a URL in config:
```json
{
"mcpServers": {
"tcg-oracle": { "url": "https://mcp.the-undesirables.com" }
}
}
```
Tools: `search_tcg_products`, `market_snapshot`,
`simulate_price`, `card_forecast`, `trending_cards`, `optimize_portfolio`,
`recommend_workflow`, `oracle_scorecard`.
Search is set-aware β `search_tcg_products("Base Set Charizard")` separates Base Set,
Base Set 2, and Shadowless rather than returning every Charizard printing. Every result
carries a `set` field and a `product_id` you can pass straight to the other tools.
---
## Two servers, one package (v2.0.0)
| Command | What it exposes | For |
|---|---|---|
| `undesirables-mcp` (default) | **The TCG Oracle β 25 tools**: search 456K+ cards (USD prices frozen 2026-09-07 β responses carry `usd_panel`), market snapshots (suspended while frozen), AI grading & grade-or-not, conformal-calibrated forecasts with a public accuracy scorecard, portfolio optimisation, card-collateral loan terms, fantasy & sports souls, the Syndicate, Technocore rooms. Backed by the public oracle API. | Anyone who wants the oracle in Claude Desktop, Cursor, Zed, LangChainβ¦ |
| `undesirables-agent-kit` | **The local agent kit β 34 tools**: memory graph, RAG over a soul workspace, meme/banner/video/3D generation, voice, code & shell execution, security audits, web search. Runs entirely on your machine. | Undesirables holders running their soul as a local agent |
v1.x shipped both surfaces under one command; v2 separates them so each server has one job. The hosted endpoint is unchanged.
## Quick Install
```bash
pip install undesirables-mcp-server
undesirables-mcp # the TCG Oracle over stdio (25 tools, no keys) β default
undesirables-agent-kit # the local 34-tool agent kit
```
Claude Desktop / Cursor / Zed β add the oracle as a stdio server:
```json
{ "mcpServers": { "undesirables-oracle": { "command": "uvx", "args": ["undesirables-mcp-server"] } } }
```
> **Turn any Undesirable NFT into an MCP-compatible AI agent with the 34-tool local agent kit (`undesirables-agent-kit`).**
---
## Table of Contents
- [What It Does](#what-it-does)
- [What's New](#whats-new-in-v210--v20x)
- [The Local Agent Kit](#-the-local-agent-kit-undesirables-agent-kit)
- [Technical Architecture (agent kit)](#technical-architecture-agent-kit)
- [Agent Framework Integration](#agent-framework-integration)
- [LitVM TCG Oracle](#litvm-tcg-oracle--mcp-server)
- [Ecosystem](#the-undesirables-ecosystem)
- [License & Commercial Use](#-license--commercial-use)
---
## What It Does
### The TCG Oracle β `undesirables-mcp` (default), 25 tools, no keys
The same 25 tools the hosted endpoint serves, over stdio. Every tool answers directly: pay-per-call is paused since 2026-10-02, so nothing asks for payment (the x402 rail stays installed and can be switched back on).
| Area | Tools |
|---|---|
| π **Search & prices** | `search_tcg_products` (455K+ products, 25+ games, set-aware), `market_snapshot`, `trending_cards` |
> **USD panel frozen 2026-09-07.** `market_snapshot`, `simulate_price`, `trending_cards` and `optimize_portfolio` are suspended (the oracle returns `{"status":"suspended"}` and does not charge); `card_forecast` and `search_tcg_products` serve the last published USD numbers and say so in-band. Live: graded-slab loan terms, sports, souls, census, crypto, Japanese two-sided quotes.
| π **Forecasts & risk** | `card_forecast` (FREE: conformal 30-day forecast + Safe-Hold / Momentum letter grades), `simulate_price` (**suspended while the USD panel is frozen** β answers `{status: suspended}`, no charge; Monte Carlo GBM / Merton paths), `optimize_portfolio` |
| π§Ύ **Public track record** | `oracle_scorecard` (30-day coverage on 181K+ matured forecasts, committed on-chain before outcomes) |
| π¦ **Card collateral** | `loan_terms_preview` (the Loan-Terms Oracle's six-step max-LTV derivation) |
| π» **Souls & leagues** | `souls_in_wallet`, `soul_calls`, `fantasy_league` (4,444 AI personalities drafting weekly lineups), `sports_board`, `jp_summary` (the Japanese dealer panel as aggregates), `graded_asks`, `loan_universe`, `census_summary`, `sports_players` (all free) |
| πΉοΈ **The Syndicate** | `syndicate_state`, `syndicate_move`, `syndicate_leaderboard` β a turn-based strategy game agents can play |
| π¬ **technocore.chat (read-only)** | `technocore_rooms`, `technocore_room`, `technocore_info`, `technocore_note` |
| π§ **Routing** | `recommend_workflow` β describe a goal, get the call sequence |
### The local agent kit β `undesirables-agent-kit`, 34 tools, runs on your machine
Turns an Undesirable NFT soul workspace into a local agent: persistent memory graph and RAG over the soul files, meme / banner / image / video / 3D generation, Kokoro TTS, ACE Step music, DuckDuckGo search, SAST code auditing, Ollama prompting, sandboxed code and shell execution, and eBay market depth. It needs Ollama and a soul workspace β see [The Local Agent Kit](#-the-local-agent-kit-undesirables-agent-kit) below. The oracle needs none of that.
---
What's New in v2.1.0 / v2.0.x
**2.1.0** β `check_accuracy` removed. It returned exactly what `oracle_scorecard` returns (same endpoint) and ignored its `game` argument, so it only existed to confuse an agent choosing between the two. Callers: switch to `oracle_scorecard`. The oracle is 27 tools.
**2.0.1** β tool descriptions rewritten so overlapping pairs state distinct jobs (`card_forecast` = free fixed 30-day read, `simulate_price` = paid custom horizon + full distribution; `market_snapshot` = the day's market report, `trending_cards` = ranked pick list; the four `technocore_*` readers numbered 1-4). `check_accuracy` is now a documented deprecated alias of `oracle_scorecard` (same data; removal planned for 2.1).
- **The oracle is the default server.** `undesirables-mcp` (and `undesirables-mcp-server`) now start the 27-tool TCG Oracle over stdio β the same tools as `https://mcp.the-undesirables.com`, with no keys, wallet, or local models.
- **The agent kit has its own command.** The 34-tool local kit moved to `undesirables-agent-kit`. Nothing was removed; each server now has one job.
- **Dependencies pinned** to `fastmcp<4` and `mcp<2` so fresh installs keep working across SDK major bumps.
- Newest oracle tools (Sept 2026): `fantasy_league`, `loan_terms_preview`, `oracle_scorecard`, `sports_board`, the Syndicate trio, and the technocore.chat readers.
- Carried over from v1.1.8: the FREE `card_forecast(card_name | product_id)` β conformal 30-day forecast plus Safe-Hold & Momentum grades in one call.
---
## π§° The Local Agent Kit (`undesirables-agent-kit`)
> Everything in this section is for the **agent kit only**. If you just want the oracle, you're already done: `uvx undesirables-mcp-server` (or the hosted URL above).
### π Prerequisites
1. **[Python](https://www.python.org/downloads/)** 3.10 or higher.
2. **[Ollama](https://ollama.com/)** β download it *and run it*. The llama icon must be in your menu bar / taskbar, or local inference fails immediately.
3. A **soul workspace** folder downloaded from [the-undesirables.com](https://the-undesirables.com) (for example `soul_folder/XXXX`).
### π οΈ Install
```bash
pip install undesirables-mcp-server
```
Or, to hack on it:
```bash
git clone https://github.com/sailorpepe/undesirables-mcp-server.git
cd undesirables-mcp-server
python3 -m venv venv && source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### π Boot
```bash
# point --workspace at your EXACT soul folder
undesirables-agent-kit --workspace "/Users/you/Desktop/soul_folder/XXXX"
```
(From a clone: `python server.py --workspace ".../soul_folder/XXXX"`.) The server has no chat window β it speaks JSON-RPC to whatever client you connect next. Don't type into that terminal.
### π Connect Claude Desktop
**Settings β Developer β Edit Config**, then:
```json
{
"mcpServers": {
"undesirables-agent-kit": {
"command": "undesirables-agent-kit",
"args": ["--workspace", "/Users/you/Desktop/soul_folder/XXXX"]
}
}
}
```
Restart Claude Desktop; the tools icon should show 34 Undesirables tools. Cursor, Zed, and Windsurf take the same `command` / `args` shape.
### π¨ Local image generation (optional)
The kit uses the 16 GB `FLUX.1-schnell` model for fully offline memes and illustrations. Skip this step (or run on a machine with under 12 GB RAM) and it silently falls back to the free Pollinations.ai cloud.
- **Apple Silicon** uses `mflux`, which needs a Hugging Face token for Black Forest Labs' gated repo: accept the terms at [black-forest-labs/FLUX.1-schnell](https://huggingface.co/black-forest-labs/FLUX.1-schnell), create a **Read** token at [Hugging Face Tokens](https://huggingface.co/settings/tokens), then run `python -c "import huggingface_hub; huggingface_hub.login()"` and paste it.
- **Nvidia CUDA / AMD DirectML** are detected automatically and use the ungated `shuttleai/FLUX.1-schnell` weights β no account needed; the first `generate a meme` downloads them.
### β οΈ Troubleshooting
- **Ollama connection refused** β Ollama isn't running. Launch the app and check for the llama icon.
- **ModuleNotFoundError: fastmcp** β you're outside the virtual environment (clone installs only). `source venv/bin/activate` first.
- **Invalid JSON: expected value at line 1** β you typed into the server terminal. Leave it alone and talk through Claude Desktop / Cursor.
---
## Technical Architecture (agent kit)
This section describes `undesirables-agent-kit`. (The oracle is a thin stdio wrapper over the same 25 tools the hosted endpoint serves; nothing below applies to it.)
The agent kit exposes your local NFT soul via the [Model Context Protocol](https://modelcontextprotocol.io) standard.
**Resources** (read only context your AI can access):
- `soul://personality` β Big Five scores, archetype, strategy, fatal flaw
- `soul://system-prompt` β The full system prompt that defines the agent
- `soul://memory` β Persistent memory (trade history, observations)
- `soul://predictions` β Prediction ledger with grades
**Agent kit tools** (34 functions your AI can call β `undesirables-agent-kit`):
- `grade_tcg_card` β 3-stage PSA/Beckett grading: Qwen Vision LLM + OpenCV centering + BGS capping
- `card_forecast` β **FREE** one-call conformal 30-day forecast + Safe-Hold/Momentum letter grades + plain-English read (pass a card name or TCGplayer product_id)
- `monte_carlo_simulation` β Price forecasting: conformal-calibrated risk by default (honest VaR/CVaR + Safe-Hold/Momentum grades); Monte Carlo GBM/Merton opt-in
- `search_ebay_market` β Live eBay market depth, price distributions, arbitrage detection
- `purchase_undesirables_license_key` β M2M purchase bridge (EVM tx payload)
- `verify_soul_initialization` β On chain soul verification
- `generate_voice` β Kokoro TTS voice synthesis
- `generate_3d_object` β Shap E text to 3D mesh (.glb)
- `generate_image` β Local FLUX image generation
- `web_search` β DuckDuckGo instant answers
- `run_security_audit` β SAST code scanning
- `query_ollama` β Send prompts to local Ollama
- `analyze_market` β Run market analysis in character
- `create_content` β Write tweets, threads, bios in character
- `meme_machine` β Generate meme concepts and marketing content
- And 20+ more covering video, audio, memory, sandbox execution
```
βββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Client (Cursor, Claude) β
ββββββββββββββββββββ¬βββββββββββββββββββββββββββ
β JSON-RPC (stdio)
ββββββββββββββββββββΌβββββββββββββββββββββββββββ
β Undesirables MCP Server β
β ββββββββββββ ββββββββββββ ββββββββββββββ β
β βResources β β Tools β β Prompts β β
β βSOUL.md β βSkills β βTemplates β β
β βMEMORY.md β βOllama β β β β
β βPredictionsβ βAnalysis β β β β
β ββββββββββββ ββββββ¬ββββββ ββββββββββββββ β
ββββββββββββββββββββββΌβββββββββββββββββββββββββ
β HTTP
ββββββββββββββββββββββΌβββββββββββββββββββββββββ
β Ollama (Local LLM) β
β llama3.1:8b / qwen / etc β
βββββββββββββββββββββββββββββββββββββββββββββββ
```
## Agent Framework Integration
### LangChain / LangGraph
```python
from langchain_mcp_adapters.client import MultiServerMCPClient
async with MultiServerMCPClient({
"undesirables": {
"command": "uvx",
"args": ["undesirables-mcp-server"]
}
}) as client:
tools = client.get_tools()
# the 25 oracle tools, now available to any LangChain agent
# (for the agent kit use command="undesirables-agent-kit", args=["--workspace", ".../soul_folder/XXXX"])
```
### CrewAI
```python
from crewai import Agent
from crewai_tools import MCPServerAdapter
mcp = MCPServerAdapter(
command="uvx", args=["undesirables-mcp-server"])
agent = Agent(
role="NFT Card Grader",
tools=mcp.tools,
goal="Grade trading cards and run calibrated price forecasts"
)
```
### OpenAI Agents SDK
```python
from agents import Agent
from agents.mcp import MCPServerStdio
mcp_server = MCPServerStdio(
command="uvx", args=["undesirables-mcp-server"])
agent = Agent(
name="Undesirables Agent",
instructions="You are a TCG market analyst. Use the oracle tools for prices, forecasts, and grading.",
mcp_servers=[mcp_server]
)
```
### ElizaOS (Merged into Official Monorepo)
```bash
npm install plugin-undesirables
```
The plugin is now part of the [official ElizaOS monorepo](https://github.com/elizaOS/eliza/tree/develop/plugins/plugin-undesirables) (PR #7869, merged May 21 2026).
Add to your `character.json`:
```json
{
"settings": {
"UNDESIRABLES_WORKSPACE": "/path/to/soul_folder/XXXX"
},
"plugins": ["plugin-undesirables"]
}
```
---
## LitVM TCG Oracle β MCP Server
We also publish a dedicated on-chain oracle MCP server for the LitecoinVM ecosystem:
```bash
pip install litvm-tcg-oracle
```
| Feature | Detail |
|---------|--------|
| **456K+ trading cards** | 25+ games, 290K actively priced |
| **13.5M+ price observations** | 60+ days of continuous data |
| **On-chain Merkle proofs** | Trustless verification on LiteForge (Chain 4441) |
| **Risk forecast** | Conformal-calibrated VaR/CVaR + Safe-Hold/Momentum grades (Monte Carlo opt-in) |
| **16 MCP tools** | `search_cards`, `get_price`, `get_merkle_proof`, `get_graded_proof`, `oracle_status`, `get_forecast`, `simulate_price`, `get_market_snapshot`, `get_jp_summary`, `get_graded_asks`, `get_loan_universe`, `get_loan_terms_preview`, `get_sports_board`, `get_fantasy_league`, `get_census_summary`, `get_oracle_scorecard` |
β **GitHub**: [litvm-tcg-oracle-mcp](https://github.com/sailorpepe/litvm-tcg-oracle-mcp)
β **PyPI**: [litvm-tcg-oracle](https://pypi.org/project/litvm-tcg-oracle/)
β **Live Oracle**: [the-undesirables.com/litvm](https://the-undesirables.com/litvm)
---
## The Undesirables Ecosystem
- **Website**: [the-undesirables.com](https://the-undesirables.com)
- **LitVM Oracle**: [the-undesirables.com/litvm](https://the-undesirables.com/litvm)
- **Mint**: [scatter.art/the-undesirables](https://scatter.art/the-undesirables)
- **Docs**: [the-undesirables.com/docs](https://the-undesirables.com/docs)
- **PyPI (MCP)**: [undesirables-mcp-server](https://pypi.org/project/undesirables-mcp-server/) (v2.0.0)
- **PyPI (LitVM)**: [litvm-tcg-oracle](https://pypi.org/project/litvm-tcg-oracle/) (v1.0.7)
- **npm**: [plugin-undesirables](https://npmjs.com/package/plugin-undesirables) (ElizaOS plugin, v2.7.0)
- **Oracle API**: [oracle.the-undesirables.com](https://oracle.the-undesirables.com) (31 endpoints, x402 micropayments)
- **awesome-mcp-servers**: [Listed β
](https://github.com/punkpeye/awesome-mcp-servers) (94K+ β, both servers listed)
- **Glama**: [Verified β
β tool quality A](https://glama.ai/mcp/servers/sailorpepe/undesirables-mcp-server)
- **ElizaOS Plugin**: [Official monorepo](https://github.com/elizaOS/eliza/tree/develop/plugins/plugin-undesirables)
- **x402 Payment Server**: [undesirables-x402-server](https://github.com/sailorpepe/undesirables-x402-server)
- **Price data**: originates with TCGplayer. No rights claimed in the underlying prices;
the modelling and on-chain proofs are ours.
- **X**: [@undesirables_ai](https://x.com/undesirables_ai)
---
## βοΈ Legal Disclaimer
**For Entertainment Purposes Only:** The Market Oracle, Trading Simulators, and all AI-generated predictions are for educational and entertainment purposes. AI models natively hallucinate. Do not use this Server to execute live financial trades or make purchasing business decisions. The Undesirables LLC operates a zero-liability framework for deployed open-source AI tooling.
---
## π License & Commercial Use
This project is licensed under the **[Business Source License 1.1 (BUSL-1.1)](https://github.com/sailorpepe/undesirables-mcp-server/blob/HEAD/LICENSE)**.
We build in public and support the developer ecosystem β but we also protect the infrastructure and IP of **The Undesirables LLC**.
### β
What You CAN Do (Free)
- **Personal & Educational Use** β Download, modify, and run locally for learning, research, or personal projects.
- **Non-Competing Applications** β Integrate our packages into your app, provided your app does not offer TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle services as its primary function.
- **MCP / Agent Integration** β Connect your AI agent to our tools for non-commercial use.
- **Community Contributions** β Security audits, bug fixes, and PRs are always welcome.
### π« What You CANNOT Do (Use Limitation)
- **Competing Service** β You may not use this code to operate a competing TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle service.
- **Commercial Resale** β You may not wrap our API, data pipelines, or AI models into a paid service without a commercial license.
- **Hosted SaaS** β You may not host this software as a service for third parties without written permission.
### π Open-Source Conversion
On **June 1, 2030** (or 4 years after the first public release of each version), this code automatically converts to the **MIT License** β fully open source, forever.
### π€ Commercial Licensing
Building a commercial product? Want guaranteed API access or white-label integration? Contact us:
π§ **oracle@the-undesirables.com** Β· π¦ **[@undesirables_ai](https://x.com/undesirables_ai)**
Β© 2026 The Undesirables LLC
---
β **If this project helped you, please star this repo** β it helps others find it.
[Report Bug](https://github.com/sailorpepe/undesirables-mcp-server/blob/HEAD/../../issues) Β· [Request Feature](https://github.com/sailorpepe/undesirables-mcp-server/blob/HEAD/../../issues)
## Data freshness
USD market prices originate from TCGPlayer. **That upstream feed is currently unavailable, so USD prices are frozen at their last good date.** Every price response carries its own `latest_date`, and the oracle root publishes live panel state under `panels` β read that rather than assuming.
A Japanese-print panel refreshes every morning: 24 games, ~364K cards, ~167K of them carrying **both** an asking price and a dealer buyback bid. Graded comps, sports boards and the proof layer are unaffected.
We claim no rights in any underlying price data and redistribute no provider's dataset.