# redm-mcp — RedM / RDR3 docs MCP server

Model Context Protocol (MCP) server for **RedM** / **RDR3**: native lookups (hash ↔ name), hybrid semantic search, static checking of agent-written scripts, framework docs (**VORP**, **RSGCore**, **ox_lib**, **oxmysql**, **Feather**), Cfx runtime docs, community-verified findings, map/location lookups, game-asset and discovery catalogs (peds, weapons, animations, AI flags, props, audio banks, catalog items) and an animation converter. Gives AI coding agents (Claude Code, Cursor, Claude Desktop, VS Code Copilot, Zed, …) exact answers instead of guesses.

Runs as a hosted HTTP-transport MCP at `https://redm-mcp.fivem.no/mcp` — no local install. Free to use; you sign in once with Discord (OAuth) when your client connects.

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_redm--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22redm-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fredm-mcp.fivem.no%2Fmcp%22%7D)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_redm--mcp-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode-insiders:mcp/install?%7B%22name%22%3A%22redm-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fredm-mcp.fivem.no%2Fmcp%22%7D)
[![Add to Cursor](https://img.shields.io/badge/Cursor-Add_redm--mcp-000000?style=flat-square&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=redm-mcp&config=eyJ1cmwiOiJodHRwczovL3JlZG0tbWNwLmZpdmVtLm5vL21jcCIsInR5cGUiOiJodHRwIn0=)

> This repository contains only installation/usage docs and serves as the issue tracker. The server source code is proprietary and not distributed. The hosted endpoint is free to use.

## Why

When an agent reads RedM code it typically encounters:

```lua
Citizen.InvokeNative(0x09C28F828EE674FA, player, 1.5, 5000)
```

Without a lookup, the agent guesses at parameters and semantics. With this server:

```
lookup_native({ hash: "0x09C28F828EE674FA" })
→ BOOST_PLAYER_HORSE_SPEED_FOR_TIME(player Player, speedBoost float, duration int)
```

The server advertises its own usage via MCP `instructions` — no skill or extra client config needed.

## Tools

| Tool | Use |
|------|-----|
| `lookup_native` | Exact lookup by hash or name (incl. old names). Warnings, usage and linked community findings; flags GTA5-only natives. |
| `semantic_search` | Hybrid (semantic + lexical, reranked) search by behavior/concept across docs, frameworks and findings. |
| `grep_docs` | Regex/literal grep across raw doc files. Needed for the large data tables that are only preview-indexed in embeddings. |
| `get_document` / `read_lines` | Fetch a doc path (optionally trimmed to relevant sections) or an exact line range. |
| `browse` / `list_namespaces` | List categories, namespaces and document paths. |
| `check_code` | Static check of a whole Lua/JS/TS script against the natives the RedM runtime actually defines: nil globals, wrong signatures/arity, cross-game natives, `InvokeNative` pitfalls, wrong client/server side. |
| `asset_lookup` | Peds, weapons, vehicles, props etc. by name, hash or type. |
| `discovery_lookup` | Search community discovery catalogs (animations, AI flags, controls, bones, events, catalog items, …). |
| `location_lookup` | Where is X, what is near these coordinates, which town is this. |
| `get_invoke_guide` | How to call natives correctly from Lua / JS. |
| `share_finding` | Share a verified gotcha so other agents find it. Findings are reviewed before they become public. |
| `create_animation_conversion`, `start_animation_conversion`, `animation_conversion_status` | Convert FiveM YCD / Mixamo FBX animations to RedM YCDs with integration steps. Offline-verified, not in-game; the operator can switch access off. |

The server also exposes MCP prompts and resources (decision tree, invoke guides, pool-size limits).

## Client setup

All clients connect to `https://redm-mcp.fivem.no/mcp`. The first connection opens a Discord sign-in (OAuth; only your Discord identity is requested, `identify` scope). Clients with built-in OAuth support (Claude Code, Cursor, VS Code, Claude Desktop connectors) handle this automatically; `mcp-remote` does the same for stdio-only clients.

VS Code and Cursor users: click an install badge above for one-click setup. For everything else, copy-paste the config below — also available as ready-made files in [`examples/`](examples/).

### Claude Code

```bash
claude mcp add --transport http redm-mcp https://redm-mcp.fivem.no/mcp
```

Or edit `~/.claude.json` manually:

```json
{
  "mcpServers": {
    "redm-mcp": {
      "type": "http",
      "url": "https://redm-mcp.fivem.no/mcp"
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project root):

```json
{
  "mcpServers": {
    "redm-mcp": {
      "url": "https://redm-mcp.fivem.no/mcp"
    }
  }
}
```

Restart Cursor. Check `Settings → MCP` for green status.

### Claude Desktop

Claude Desktop doesn't support HTTP MCP directly — use `mcp-remote` as a proxy. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "redm-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://redm-mcp.fivem.no/mcp"
      ]
    }
  }
}
```

Restart Claude Desktop.

### VS Code (Copilot / Continue)

`.vscode/mcp.json` in a project root:

```json
{
  "servers": {
    "redm-mcp": {
      "type": "http",
      "url": "https://redm-mcp.fivem.no/mcp"
    }
  }
}
```

### Zed

`~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "redm-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://redm-mcp.fivem.no/mcp"
        ]
      }
    }
  }
}
```

### Other clients (generic)

- HTTP transport clients: point to `https://redm-mcp.fivem.no/mcp`
- stdio-only clients: use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a proxy

## Verify it works

1. `curl https://redm-mcp.fivem.no/health` → `{"ok":true}`
2. `curl https://redm-mcp.fivem.no/ingest-status` → shows version and last ingested timestamp
3. In your client: sign in with Discord when prompted, then ask the agent to look up `0x09C28F828EE674FA` — should return `BOOST_PLAYER_HORSE_SPEED_FOR_TIME`

## Endpoints

| Path | Auth | Purpose |
|------|------|---------|
| `POST /mcp` | Discord OAuth | MCP protocol |
| `GET /health` | no | Liveness |
| `GET /ingest-status` | no | `{ current, last, ingestedAt, upToDate }` |

Usage is logged per tool call (tool, arguments, Discord identity) to operate and improve the service. Scripts sent to `check_code` are stored with secrets masked for 90 days.

## Example prompts

See [`examples/prompts.md`](examples/prompts.md) for things to try once installed (native lookups, behavior searches, framework / inventory questions, debugging).

## Issues / feedback

Bug, missing docs, incorrect native lookups, requests for new tools? [Open an issue](../../issues/new).

## Doc sources

Indexed upstreams:
- [femga/rdr3_discoveries](https://github.com/femga/rdr3_discoveries) — community ped/weapon/anim/prop hashes, AI flags, enums
- [VORPCORE/documentation](https://github.com/VORPCORE/documentation), [rsgcore.com](https://rsgcore.com), [overextended](https://github.com/overextended) (`ox_lib`, `oxmysql`), Feather and community repos — framework and library docs
- [VORPCORE/RDR3natives](https://github.com/VORPCORE/RDR3natives) and the Cfx native dumps — natives
- [citizenfx/fivem-docs](https://github.com/citizenfx/fivem-docs) — Cfx runtime/scripting docs
- [jeanropke/RDOMap](https://github.com/jeanropke/RDOMap) — map locations
- Community findings shared through `share_finding`