# Arma 3 MCP server: SQF reference and linter for AI agents

The a3ref MCP server gives Claude Code, Codex, Antigravity, OpenCode, Cursor, VS Code and any other
[MCP](https://modelcontextprotocol.io) client the complete Arma 3 scripting reference, mirrored daily from the
Bohemia Interactive Community Wiki, and checks SQF for the mistakes language models make most: made-up commands,
missing operands, unknown functions and deprecated commands.

It is free and open source (MIT), needs no account or API key, and runs on Windows, macOS and Linux. It covers
every scripting command, every `BIS_fnc_*` function and the core concept pages: data types, locality, the
scheduler, event handlers.

## What the agent gets

| Tool | What it does |
|---|---|
| `search` | Find commands, functions, event handlers and topics by name, partial name, operator symbol (`>>`, `!=`) or by what they do ("delete vehicle") |
| `get` | Read a page: syntax, typed parameters, return value, locality, examples, community notes. Any spelling works (`SETPOS`, `spawnGroup`, `bis fnc spawngroup`); an event handler's name (`AnimStateChanged`, `Draw3D`, `onLoad`) returns its section; `section` returns one part of a long topic |
| `list_group` | Everything in a command or function group ("Multiplayer", "Object Manipulation", ...) |
| `lint_sqf` | Check SQF: made-up commands, commands used without their left operand or argument, unknown `BIS_fnc_*` functions, deprecated or broken commands, diagnostic-build-only commands, `format` strings missing values, unknown event handler names |
| `recent_changes` | What changed on the wiki recently |

What `lint_sqf` reports:

```text title="lint_sqf"
Checked 3 lines: 2 errors, 1 warnings, 0 notes.

1:8 error: Unknown command setUnitHealth (used as a binary command).
2:1 error: setPos needs a left operand. Syntax: `object setPos pos`.
3:4 warning: ctrlSetEventHandler is deprecated. Use ctrlAddEventHandler instead.
```

The linter only reports what cannot be valid SQF, so it stays quiet on correct code. Run over the 5,500 SQF
examples on the wiki, it reports 23 errors, nearly all of them config or prose pasted into code blocks.

## Install

All you need is [Node.js](https://nodejs.org/) 18 or newer. Where a client has plugins, the plugin is the
easiest way: it adds the MCP server and the `sqf` skill, which tells the agent to look commands up and lint SQF
before showing it. Otherwise add the server to the client's MCP settings; every client starts the same command,
`npx -y a3ref-mcp`.

AI agents asked to install the server: use the terminal command of the client you run in, then tell the user
to restart the client or reload its MCP servers.

### Claude Code

**Plugin.** Type in Claude Code:

```text title="Claude Code"
/plugin marketplace add a3ref/mcp
/plugin install a3ref@a3ref
```

**Server only**, for every project (leave out `--scope user` for the current project only):

```sh title="Terminal"
claude mcp add --scope user a3ref -- npx -y a3ref-mcp
```

Check with `/mcp` in Claude Code: `a3ref` should be listed as connected.

### Codex

**Plugin.** The Codex CLI, the Codex IDE extension and the ChatGPT desktop app share plugins and settings, so one
install covers all three:

```sh title="Terminal"
codex plugin marketplace add a3ref/mcp
codex plugin add a3ref@a3ref
```

Or, after adding the marketplace, install `a3ref` from the Plugins directory of the ChatGPT desktop app.

**Server only:**

```sh title="Terminal"
codex mcp add a3ref -- npx -y a3ref-mcp
```

Or add it yourself to `~/.codex/config.toml` (or to `.codex/config.toml` in a trusted project):

```toml title="~/.codex/config.toml"
[mcp_servers.a3ref]
command = "npx"
args = ["-y", "a3ref-mcp"]
```

Check with `codex mcp list` in a terminal or `/mcp` in the Codex CLI.

### Antigravity

**Plugin.** Plugins installed with the CLI or the Antigravity app are available in the app, the IDE and the CLI:

```sh title="Terminal"
agy plugin install https://github.com/a3ref/mcp
```

**Server only.** The Antigravity app, the IDE and the CLI (`agy`) read the same file, `~/.gemini/config/mcp_config.json`
(or `.agents/mcp_config.json` for one workspace). In the IDE, the agent panel's menu (…), MCP Servers, Manage MCP
Servers, View raw config opens it.

```json title="~/.gemini/config/mcp_config.json"
{
  "mcpServers": {
    "a3ref": {
      "command": "npx",
      "args": ["-y", "a3ref-mcp"]
    }
  }
}
```

In the CLI, `/mcp` opens the MCP manager: it shows whether the server is connected and reloads the settings.
Antigravity CLI replaced Gemini CLI in 2026; set the server up there as shown here.

### OpenCode

Add the server to `~/.config/opencode/opencode.json` for every project, or to `opencode.json` in one project:

```json title="~/.config/opencode/opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "a3ref": {
      "type": "local",
      "command": ["npx", "-y", "a3ref-mcp"],
      "enabled": true
    }
  }
}
```

Check with `opencode mcp list`. For the `sqf` skill as well, save
[its SKILL.md](https://github.com/a3ref/mcp/blob/main/skills/sqf/SKILL.md) as
`~/.config/opencode/skills/sqf/SKILL.md`. OpenCode plugins are code modules rather than packages of servers and
skills, so there is no plugin to install.

### Claude Desktop

Settings, Developer, Edit Config opens `claude_desktop_config.json` (in `%APPDATA%\Claude\` on Windows,
`~/Library/Application Support/Claude/` on macOS). Add the server and restart Claude Desktop:

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "a3ref": {
      "command": "npx",
      "args": ["-y", "a3ref-mcp"]
    }
  }
}
```

### Cursor

In `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` in one project:

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "a3ref": {
      "command": "npx",
      "args": ["-y", "a3ref-mcp"]
    }
  }
}
```

### Windsurf

```json title="~/.codeium/windsurf/mcp_config.json"
{
  "mcpServers": {
    "a3ref": {
      "command": "npx",
      "args": ["-y", "a3ref-mcp"]
    }
  }
}
```

### VS Code

For Copilot agent mode, in the workspace:

```json title=".vscode/mcp.json"
{
  "servers": {
    "a3ref": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "a3ref-mcp"]
    }
  }
}
```

### Other clients

Any client that runs local (stdio) MCP servers works: give it the command `npx` with the arguments
`-y a3ref-mcp`. Most take the `mcpServers` JSON shown for Cursor.

## Try it

Ask the agent something that needs the reference, for example:

- "Which command deletes a vehicle with its crew? Check the locality."
- "Spawn a group of four NATO riflemen near the player, then lint the script."
- "What changed on the Arma 3 wiki this week?"

The agent should call `search`, `get` or `lint_sqf` instead of answering from memory.

## Troubleshooting

- **The server does not start.** Run `node --version` (18 or newer is needed), then
  `npx -y a3ref-mcp` in a terminal: it should start and wait for input without printing anything
  (Ctrl+C ends it).
- **`npm error code EALLOWGIT`.** An older setup runs `npx -y github:a3ref/mcp`, which npm 12 refuses (it no longer
  installs packages straight from git). Replace `github:a3ref/mcp` with `a3ref-mcp`.
- **Windows: the client cannot find `npx`.** Some clients do not run `.cmd` files directly. Use the command `cmd`
  with the arguments `/c npx -y a3ref-mcp`, e.g. `"command": "cmd", "args": ["/c", "npx", "-y", "a3ref-mcp"]`.
- **Your own copy of the site.** The server reads https://wiki.arma3.io/; set the environment variable
  `A3REF_BASE_URL` to read a mirror instead.

## How it works

The server downloads what it needs from this site (`index.json`, `syntax.json` and the pages the agent asks for)
and keeps it in memory for an hour. Nothing is bundled, so answers follow the wiki without updating the server.

No MCP client? Every page of this site is also plain Markdown and JSON at a stable URL; an agent that can fetch
web pages can start from [llms.txt](https://wiki.arma3.io/llms.txt). The source code, issues and release notes
are on [GitHub](https://github.com/a3ref/mcp).