undesirables-mcp-server

<!-- mcp-name: io.github.sailorpepe/undesirables-mcp-server --> <div align="center">

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 · Docs · PyPI · 𝕏

</div> <div align="center"> <img src="https://raw.githubusercontent.com/sailorpepe/undesirables-mcp-server/main/assets/demo.gif" alt="Undesirables MCP Server Demo" width="480" /> </div>

---

🔌 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:

{
  "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

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:

{ "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's New
• The Local Agent Kit
• Technical Architecture (agent kit)
• Agent Framework Integration
• LitVM TCG Oracle
• Ecosystem
• 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 below. The oracle needs none of that.

---

<details> <summary><strong>What's New in v2.1.0 / v2.0.x</strong></summary>

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.

</details>

---

🧰 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 3.10 or higher.
2. Ollama — 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 (for example soul_folder/XXXX).

🛠️ Install

pip install undesirables-mcp-server

Or, to hack on it:

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

# 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:

{
  "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, create a Read token at Hugging Face 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.
• **Modu