# Canada Travel Advisory MCP Server

An MCP server for Government of Canada travel advisories, backed by the Global Affairs Canada
open data index of 230 destinations.

Lightweight by design: a single `index.js`, one dependency (`@modelcontextprotocol/sdk`),
no build step, no TypeScript compile, no HTTP library.

## Install

```bash
npm install
```

Requires Node.js 18+ (uses the built-in `fetch`).

## Setup

No API key is needed — the dataset is public and unauthenticated. All clients below run the same
stdio command: `node <path-to>/index.js`.

Substitute your own absolute path if the project lives elsewhere.

### Claude Code

```bash
claude mcp add canada-travel-advisory -- node E:/Claude/mcp-servers/canada-travel-advisory/index.js
```

Add `--scope user` to make it available across all your projects instead of just the current one.

### Claude Desktop

In `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "canada-travel-advisory": {
      "command": "node",
      "args": ["E:/Claude/mcp-servers/canada-travel-advisory/index.js"]
    }
  }
}
```

Restart Claude Desktop after saving.

### Codex CLI

```bash
codex mcp add canada-travel-advisory -- node E:/Claude/mcp-servers/canada-travel-advisory/index.js
```

Or edit `~/.codex/config.toml` directly (use `.codex/config.toml` in the project root to scope it
to one trusted project):

```toml
[mcp_servers.canada-travel-advisory]
command = "node"
args = ["E:/Claude/mcp-servers/canada-travel-advisory/index.js"]
```

Verify with `codex mcp list`.

### Cursor

Create `.cursor/mcp.json` in the project root, or `~/.cursor/mcp.json` to enable it globally:

```json
{
  "mcpServers": {
    "canada-travel-advisory": {
      "command": "node",
      "args": ["E:/Claude/mcp-servers/canada-travel-advisory/index.js"]
    }
  }
}
```

The server then appears under Settings → MCP, where it must be toggled on.

### Windows path note

The forward slashes above work fine on Windows. If you prefer backslashes in the JSON configs,
escape them: `"E:\\Claude\\mcp-servers\\canada-travel-advisory\\index.js"`.

## Tools

| Tool | Purpose |
|---|---|
| `get_travel_advisory` | Advisory for one destination. Accepts a name (English or French), ISO code (`JP`), or slug (`costa-rica`). Ambiguous input returns candidates. |
| `list_travel_advisories` | Filter and browse all destinations by `risk_level`, `min_risk_level`, `has_regional_advisory`; sort by `name` / `risk` / `updated`; paged via `limit` + `offset`. |
| `get_recent_updates` | Advisories changed most recently, newest first. Filter by `days` and by `update_type`. |
| `search_countries` | Partial-match search across names, ISO codes, and slugs. |
| `compare_advisories` | Compare several destinations at once, ranked highest risk first. |
| `get_advisory_statistics` | Dataset overview: counts per risk level, regional-advisory count, change-type breakdown, freshness. |

All tools accept `language` (`"en"` default, or `"fr"`), which switches names, advisory text, and
the destination link between `travel.gc.ca` and `voyage.gc.ca`.

### Risk levels

| Level | Meaning |
|---|---|
| 0 | Exercise normal security precautions |
| 1 | Exercise a high degree of caution |
| 2 | Avoid non-essential travel |
| 3 | Avoid all travel |

`min_risk_level: 2` gives every destination Canada advises against travelling to. Filters also
accept the label text (e.g. `risk_level: "avoid all travel"`).

### Example questions this answers

- "What's the travel advisory for Peru?"
- "Which countries should I avoid all travel to right now?"
- "What advisories changed in the last week?"
- "Compare Japan, Mali, and France for a trip."
- "How many destinations have regional advisories?"

## Data source and behaviour notes

Source: `https://data.international.gc.ca/travel-voyage/index-alpha-eng.json`

- **One endpoint is fetched, not two.** The published `index-updated.json` is byte-identical to
  `index-alpha-eng.json` (verified: same MD5, same alphabetical key order) and is *not* actually
  sorted by recency. `get_recent_updates` therefore sorts on `date-published.timestamp` locally,
  which is reliable regardless of what order the upstream file happens to be in.
- **One fetch serves both languages.** Despite the `-eng` suffix, every record embeds both `eng`
  and `fra` blocks; the `-fra` file differs only in key order.
- **Caching**: responses are cached in memory for 60 minutes (the dataset regenerates about
  hourly), refreshed with conditional `If-None-Match` / `If-Modified-Since` requests. If a refresh
  fails, the last good data is served with `stale: true` rather than erroring.
- **Summary data only.** The dataset carries risk level, advisory text, update date and change
  summary. Full advisory detail (safety and security, entry requirements, health, regional
  breakdowns) exists only as HTML, so every result includes the destination `url` to read it.

Every response also carries `data_generated` (upstream generation time) and a source attribution
line, so answers can be dated.

## Licence

MIT. Advisory data © Government of Canada, used under the
[Open Government Licence – Canada](https://open.canada.ca/en/open-government-licence-canada).