Skip to main content
Glama
README.md
# uex-market-mcp

Search the [UEX](https://uexcorp.space/marketplace/) player marketplace of
Star Citizen from Claude, or any MCP client, with combined filters:

> *List recent listings of Stileron sellers with quality above 800.*

One call combines item, quality range, age, price, star system, location,
seller, title words and category, ranked by quality, recency or price, one
listing per seller, each with a direct link.

Read-only, public data, no UEX account and no secret needed.

## Use it

**Hosted instance** (free, public, rate limited): `https://uex.cavalera.news/mcp`

- Claude web / desktop / mobile: *Settings > Connectors > Add custom connector*, paste the URL.
- Claude Code: `claude mcp add --transport http uex-market https://uex.cavalera.news/mcp`

**Local, no third-party server** (needs [uv](https://docs.astral.sh/uv/)):

```json
{
  "mcpServers": {
    "uex-market": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jbillochon/uex-market-mcp", "uex-market-mcp"]
    }
  }
}
```

or `claude mcp add uex-market -- uvx --from git+https://github.com/jbillochon/uex-market-mcp uex-market-mcp`.
Calls then go from your machine straight to the UEX API.

**Skill**: `skill/uex-marketplace/SKILL.md` teaches Claude how to turn a
request into filters and how to read quality labels. Zip the
`uex-marketplace` folder and add it in Claude (*Settings > Capabilities >
Skills*), or copy it to `~/.claude/skills/` for Claude Code.

## Tools

| Tool | Purpose |
|---|---|
| `search_listings` | Filtered, ranked listings. Main tool. |
| `find_items` | Typo-tolerant lookup in the UEX catalog (about 7 800 items). |
| `marketplace_status` | Catalog and cache freshness, UEX call budget. |

## How quality is read

Sellers often leave the quality field empty or at its default, and write
the real value in the title (`Dolivine 886Q`, `Q965`, `550-676q`). Each
result says where its quality comes from:

| Label | Meaning |
|---|---|
| `974` | declared by the seller |
| `~886` | read from the title or description |
| `517-747` | one listing offering several qualities (filtered on the range) |
| `500?` | the form default, not confirmed |
| `?` | unknown, never passes a quality threshold |

The parser abstains rather than guess: prices, volumes and quantities
(`585 400 000`, `32 SCU`, `x50`) are not read as qualities.

## Data and limits

- Per item: every active listing (up to 1 000), live from the UEX API,
  cached 10 minutes.
- Listings published without an item id (about one in seven) are found by
  title among the latest 1 000 listings of the marketplace, polled at most
  every 5 minutes and kept for 21 days.
- A search without an item covers that recent window only.
- Sold-out and expired listings are dropped.
- Outgoing UEX traffic is capped per process (`UEX_MAX_CALLS_PER_MIN`,
  default 40), whatever the incoming load.

## Self-hosting over HTTP

```bash
pip install git+https://github.com/jbillochon/uex-market-mcp
UEX_MCP_ALLOWED_HOSTS=uex.example.org uex-market-mcp --http --port 8792
```

Stateless Streamable HTTP on `127.0.0.1:8792/mcp`, `/health` for probes.
Put it behind a TLS reverse proxy; `deploy/` has a systemd unit and an nginx
example with rate limiting.

| Variable | Default | |
|---|---|---|
| `UEX_MCP_ALLOWED_HOSTS` | | public host names accepted (DNS rebinding protection) |
| `UEX_MARKET_CACHE` | `~/.cache/uex-market` | catalog cache |
| `UEX_MAX_CALLS_PER_MIN` | `40` | outgoing UEX budget |
| `UEX_TOKEN` | | optional UEX token, for a quota of your own |
| `UEX_MCP_OAUTH_SHIM` | off | `1`: auto-approving OAuth facade (see below) |
| `UEX_MCP_PUBLIC_URL` | | public base URL, required by the OAuth facade |
| `UEX_MCP_OAUTH_REDIRECT_HOSTS` | `claude.ai,claude.com,localhost,127.0.0.1` | redirect hosts accepted by the facade |

**claude.ai and OAuth.** claude.ai custom connectors run OAuth discovery and
dynamic client registration on "Connect" even for servers without
authentication, and fail when there is no registration endpoint
([anthropics/claude-ai-mcp#457](https://github.com/anthropics/claude-ai-mcp/issues/457)).
`UEX_MCP_OAUTH_SHIM=1` answers that flow with an auto-approving facade: any
client registers, `/authorize` redirects straight back, `/token` issues a
token that grants nothing more, since `/mcp` stays open to everyone. Redirect
URIs are restricted to an allowlist so `/authorize` is not an open redirector.

## Development

```bash
python -m unittest discover -s tests
```

Not affiliated with UEX Corp or Cloud Imperium Games. Trades happen between
players: check the seller before paying.

MIT License.

TDQS

A3.6/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct role: find_items resolves catalog items, search_listings queries marketplace listings, and marketplace_status reports cache freshness/budget. There is no practical overlap that would cause misselection.

Naming Consistency4/5

All names use snake_case, and search_listings/find_items follow a clear verb_noun pattern. marketplace_status deviates slightly as a noun phrase, but the set remains readable and predictable.

Tool Count4/5

Three tools is modest but appropriate for a focused, read-only marketplace search server. Each tool serves a clear purpose, though the surface is on the minimal side.

Completeness3/5

The set covers item lookup, listing search, and cache status, but lacks direct retrieval of listing details by ID or deeper item details. Relying on external links for listing details is a notable gap for an agent-driven workflow.