undesirables-mcp-server

<!-- mcp-name: io.github.sailorpepe/undesirables-mcp-server -->

<div align="center">

![The Undesirables MCP Banner](https://raw.githubusercontent.com/sailorpepe/undesirables-mcp-server/main/og_preview.png)

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg?style=flat-square)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/powered%20by-FastMCP-green.svg?style=flat-square)](https://github.com/modelcontextprotocol/fastmcp)
[![License: BSL-1.1](https://img.shields.io/badge/License-BSL_1.1-orange.svg?style=flat-square)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/undesirables-mcp-server.svg?style=flat-square)](https://pypi.org/project/undesirables-mcp-server/)

**35+ local compute tools for AI agents — plus a hosted, conformal-calibrated pricing oracle**

*Run it fully local with zero cloud dependency, or connect to the hosted endpoint at `mcp.the-undesirables.com` — 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)

</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
```

No install, no account, no API key. **12 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`, `grade_card`, `grade_or_not`,
`simulate_price`, `card_forecast`, `trending_cards`, `optimize_portfolio`,
`recommend_workflow`, `check_accuracy`.

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.

---

## Quick Install

```bash
pip install undesirables-mcp-server
```

> **Turn any Undesirable NFT into an MCP-compatible AI agent with 35+ local compute tools.**

---

## Table of Contents

- [What It Does](#what-it-does)
- [What's New in v1.1.8](#whats-new-in-v118)
- [Prerequisites](#-prerequisites-read-carefully)
- [Full Setup](#-step-1-install--clone)
- [Boot The Server](#-step-2-boot-the-server)
- [Connect Your Chat Front-End](#-step-3-connect-your-chat-front-end)
- [Local Image Generation](#-step-4-setup-local-image-generation-optional)
- [Troubleshooting](#%EF%B8%8F-common-idiot-proof-diagnostics)
- [Technical Architecture](#technical-architecture-for-developers)
- [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

- 🎴 **Vision AI Card Grading** — PSA/Beckett prediction via Qwen VL
- 📊 **Conformal Risk Forecast** — calibrated VaR/CVaR + Safe-Hold & Momentum letter grades (Monte Carlo GBM/Merton opt-in)
- 🎵 **AI Music Generation** — ACE Step on Apple Silicon
- 🎬 **Video Clipping & Beat Sync Editing** — FFmpeg
- 🖼️ **Local Image Generation** — MLX Flux on Mac, DirectML on Windows, CUDA on Linux
- 🗣️ **Text to Speech Voice Engine** — Kokoro TTS
- 🧠 **Persistent RAG Memory Graphs** — CRM node mapping
- 🔍 **Zero Token Web Search** — DuckDuckGo
- 🔒 **SAST Code Security Auditing**
- 📈 **Financial Analytics Oracle** — TCGCSV + eBay depth analysis

---

<details>
<summary><strong>What's New in v1.1.8</strong></summary>

**v1.1.8** adds the FREE `card_forecast(card_name | product_id)` tool — one call returns the conformal 30-day price forecast **plus Safe-Hold & Momentum letter grades** and a one-line plain-English read (e.g. _"~12% chance it's below $Y in 30 days; Safe-Hold B, Momentum A"_). No payment required.

The **conformal-calibrated risk forecast** is the default model — regime-aware split-conformal bands with honest VaR/CVaR, plus Safe-Hold & Momentum letter grades. Monte Carlo (GBM / Merton Jump-Diffusion) remains available opt-in via `model=`. Also: corrected license badge and full ecosystem integration.

**Key Features:**
- `purchase_undesirables_license_key` — Returns an unsigned EVM transaction payload (Ethereum Mainnet, chainId 1) for autonomous agents to mint directly from the Scatter.art contract
- `verify_soul_initialization` — Verifies on chain purchase via public RPC and initializes the cryptographic soul matrix, unlocking all local compute engines
- Verified on [Glama.ai](https://glama.ai/mcp/servers/sailorpepe/undesirables-mcp-server) with a 3.8/5 quality score across 36 tools
- Listed on 9+ MCP directories including the [Official MCP Registry](https://registry.modelcontextprotocol.io)

</details>

---

## 🛑 Prerequisites (Read Carefully)
If you've never used Python or run AI Models locally, you **must** do this first:
1. **[Download Python](https://www.python.org/downloads/)** (Version 3.10 or higher).
2. **[Download Ollama](https://ollama.com/)**. **CRITICAL:** You cannot just download the app and leave it in your downloads folder. You must double-click the Ollama app to *physically run it*. You should see a little llama icon in your Mac menu bar or Windows system tray for this server to work. 

---

## 🛠️ Step 1: Install & Clone

First, open your Terminal or Command Prompt and clone this repository. After cloning, you must activate a "Virtual Environment" (a sandbox folder just for this codebase).

### 🍎 On Mac / Linux
```bash
git clone https://github.com/sailorpepe/undesirables-mcp-server.git
cd undesirables-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 🪟 On Windows
```bash
git clone https://github.com/sailorpepe/undesirables-mcp-server.git
cd undesirables-mcp-server
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```

---

## 🚀 Step 2: Boot The Server

Every single time you want to run this server later, you must open your terminal and make sure your Virtual Environment is activated `(venv)` first!

If you already downloaded your Soul Workspace from the website:
```bash
# Make sure to point to your EXACT soul folder path
python server.py --workspace "/Users/username/Desktop/soul_folder/0420"
```

---

## 🔌 Step 3: Connect Your Chat Front-End

The MCP Server doesn't have a chat window; it runs invisibly in the background of your terminal! To actually talk to your agent, you must connect it to a desktop application like Claude or Cursor.

### Claude Desktop Connection
1. Open the Claude Desktop application on your computer.
2. Go to **Settings > Developer > Edit Config**.
3. Paste this into your config file, making absolutely sure you replace the `cwd` (Current Working Directory) with your exact folder path:
```json
{
  "mcpServers": {
    "undesirables": {
      "command": "python",
      "args": ["server.py", "--workspace", "/Users/yourname/Desktop/soul_folder/0420"],
      "cwd": "/Users/yourname/Documents/undesirables-mcp-server"
    }
  }
}
```
4. Restart the Claude Desktop app. You should see a little "Plugin/Hammer" icon telling you that 35+ The Undesirables tools are now available!

---

## 🎨 Step 4: Setup Local Image Generation (Optional)

If you want your agent to physically generate memes and illustrations 100% offline natively on your computer, the MCP Server uses the massively powerful 16GB `FLUX.1-schnell` model. 

If you do not complete this step, or if your computer is too weak (< 12GB RAM), the server will automatically fallback and generate memes for you silently via the free `Pollinations.ai` cloud network.

### 🍏 Authenticating Apple Silicon (Mac M1/M2/M3/M4)
Apple Silicon specifically uses `mflux`, which strictly requires a Hugging Face token to bypass Black Forest Labs' legal compliance gate.
1. Navigate to **[black-forest-labs/FLUX.1-schnell](https://huggingface.co/black-forest-labs/FLUX.1-schnell)**, create a free Hugging Face account, and click **Agree and Access**.
2. Go to **[Hugging Face Tokens](https://huggingface.co/settings/tokens)** and generate a new **Read** token.
3. Open your Mac terminal, activate your virtual environment, and log in:
```bash
cd undesirables-mcp-server
source venv/bin/activate
python -c "import huggingface_hub; huggingface_hub.login()"
```
4. Paste your token and press **Enter** *(your clipboard characters will be invisible for security)*.

### 🪟 Setup for Windows/Linux GPUs
If your computer uses Nvidia CUDA or AMD DirectML, the diagnostic scanner detects this and logically shifts your engine to an **ungated open-weights repository** (`shuttleai/FLUX.1-schnell`).
- **You do not need to authenticate anything or make an account.**
- Simply ask your agent to `generate a meme` in the UI! Your system will natively download the 16GB weights fully offline during the very first execution automatically.

---

## ⚠️ Common Idiot-Proof Diagnostics

If your terminal throws red text and halts, check these top 3 reasons:

- **Error: Ollama connection refused**
  Your AI's brain is offline! Make sure you physically double-clicked the *