# gtrmarket-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server for the
[gtrmarket](https://gtrmarket.com) API: the Nissan Skyline GT-R production
registry, a parts fitment graph, live marketplace listings, and a searchable
index of two decades of Skyline forum threads.

It exists because these are *facts*, and a language model answering from memory
will get them subtly wrong. Production numbers, part numbers, what fits a
BNR34 and what does not — these have sources, and an assistant should be
reading them rather than recalling them.

## Install

Add it to your MCP client. For Claude Desktop or Claude Code:

```json
{
  "mcpServers": {
    "gtrmarket": {
      "command": "npx",
      "args": ["-y", "gtrmarket-mcp"],
      "env": {
        "GTRMARKET_API_KEY": "gtrm_live_..."
      }
    }
  }
}
```

Create a key at <https://gtrmarket.com/settings/developer>. A read-only key with
`market:read`, `registry:read`, `parts:read` and `archive:read` is all this
server needs, and it is what we recommend — see [Safety](#safety).

The secret is shown once and never again, so paste it into your config before
you close the page.

## Tools

| Tool | What it does |
|---|---|
| `list_chassis` | Every Skyline chassis code, with generation, years, drivetrain and body. Use it to resolve "an R34 GT-R" to `BNR34`. |
| `get_chassis` | One chassis in full, including its factory engines and trims. |
| `decode_vin` | Turn `BNR34-001234` into a model, generation, grade and production window. Works whether or not the car is in the registry. |
| `search_registry` | Search recorded chassis numbers by code, grade, paint, transmission, year or country. |
| `production_figures` | Sourced production numbers and paint distribution for a chassis. |
| `search_listings` | Search the marketplace, with chassis and engine fitment filters. |
| `search_parts` | Search the parts catalogue. |
| `parts_for_chassis` | Everything recorded as fitting one chassis. |
| `check_compatibility` | Check a set of parts against a vehicle and against each other. |
| `search_archive` | Search indexed threads across several Skyline forums. |

## Safety

**Every tool is read-only.** Nothing here posts, edits, buys or deletes. An
assistant that can search is useful; one that can list your car for sale is a
different decision, and it should be made deliberately by somebody who has read
the code — not inherited by installing an MCP server.

**It is a thin wrapper.** Every tool maps to exactly one documented endpoint of
the public API. There is nothing this server can do that you could not do with
`curl`, which is the property that makes it reasonable to hand it a key. Read
[`src/tools.ts`](src/tools.ts) before you do; it is short.

**Your key limits it further.** A gtrmarket API key can never do more than the
account that created it, and its scopes narrow it from there. Give this server
a key with only the read scopes and it cannot write even if you asked it to.

## Attribution

The archive is an **index of other people's forums, not a copy of them**. Every
result carries its source and a link back, and where we have no permission to
reproduce the posts, a result is a title and a link and nothing more. If you
surface these results, show the source and link back — the same terms we
operate under.

The registry, the fitment graph and the production figures exist because
members contributed them. Build on them; keep the attribution.

## Configuration

| Variable | Required | Default |
|---|---|---|
| `GTRMARKET_API_KEY` | yes | — |
| `GTRMARKET_API_URL` | no | `https://gtrmarket.com/api/v1` |

`GTRMARKET_API_URL` exists for testing against a local instance. You will not
need it.

## Rate limits

A free key allows 60 requests a minute and 5,000 a day. Some tools cost more
than one request against that budget: `search_archive` and
`check_compatibility` cost 5, the search tools cost 2. If you hit the limit the
server returns a message saying so rather than failing silently, so the
assistant can tell you.

Full details: <https://gtrmarket.com/developers/en/guides/rate-limits>

## Development

```bash
npm install
npm run build
GTRMARKET_API_KEY=gtrm_live_... node dist/index.js
```

The server speaks MCP over stdio. `stdout` is the protocol channel — anything
written there corrupts it, which is why every diagnostic goes to `stderr`.

## Documentation

- API reference and guides: <https://gtrmarket.com/developers>
- OpenAPI description: <https://gtrmarket.com/api/v1/openapi.json>

## Licence

MIT. See [LICENSE](LICENSE).