@squawk/mcp

Model Context Protocol (MCP) server that exposes the squawk aviation libraries as tools for LLM clients like Claude Desktop, Cursor, and any other MCP-compatible host. A single npx @squawk/mcp command starts a stdio server that surfaces airports, navaids, fixes, airways, procedures, airspace, ICAO aircraft registrations, weather (parsing and live AWC fetch), NOTAMs, flight plan parsing, great-circle geometry, and an E6B-style flight computer.

Part of the @squawk aviation library suite. See all packages on npm.

Quick start

Pick the snippet for your MCP client. Each one tells the host to spawn npx @squawk/mcp over stdio. After editing the config, restart the client; a squawk (or @squawk/mcp) entry should appear in the tool picker.

Claude Desktop

Open claude_desktop_config.json via Settings -> Developer -> Edit Config:

{
  "mcpServers": {
    "squawk": {
      "command": "npx",
      "args": ["-y", "@squawk/mcp"]
    }
  }
}
Copy

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project) - same shape as Claude Desktop:

{
  "mcpServers": {
    "squawk": {
      "command": "npx",
      "args": ["-y", "@squawk/mcp"]
    }
  }
}
Copy

VS Code (GitHub Copilot Chat)

VS Code 1.99+ ships an MCP runtime that GitHub Copilot Chat can call into agent mode. Add to .vscode/mcp.json in your workspace, or to the user-level config via the MCP: Add Server command:

{
  "servers": {
    "squawk": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@squawk/mcp"]
    }
  }
}
Copy

Note the schema differs from the other clients: VS Code uses servers (not mcpServers) and requires an explicit "type": "stdio".

Continue.dev

Continue exposes MCP via its experimental config block. In ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@squawk/mcp"]
        }
      }
    ]
  }
}
Copy

Picking an install version

The snippets above pass the bare package name (@squawk/mcp), which lets npx pick whatever version it finds first - usually a previously cached one. For predictable behavior, pin the version explicitly in the client config:

{
  "mcpServers": {
    "squawk": {
      "command": "npx",
      "args": ["-y", "@squawk/mcp@0.5.0"]
    }
  }
}
Copy

Bump the pinned version when a new release ships (see npm for the latest). Pinning is the most reliable option because the resolved version is part of your config and never depends on cache state.

If you would rather have the server auto-update on every Claude Desktop (or other host) restart, use the @latest tag:

{
  "mcpServers": {
    "squawk": {
      "command": "npx",
      "args": ["-y", "@squawk/mcp@latest"]
    }
  }
}
Copy

@latest instructs npx to consult the registry for the newest version on every spawn. There is a caveat: the npx cache (under ~/.npm/_npx/) can still hold an older version that satisfies the resolved tag, in which case the cached copy is reused. If a newer release is published and the server still serves the old behavior after a host restart, clear the cache directory and restart again, or fall back to a pinned version. The host process itself also has to restart for any update to take effect, since each MCP server is a long-running stdio subprocess that loads its code once at spawn time.

Pinning a specific Node binary

npx resolves node through whatever PATH the host launches with. On macOS, GUI apps often inherit a different PATH than your shell, so you may end up running an older Node than which node shows. Live weather fetch tools require Node >= 22 (for global fetch). If the startup log shows WARNING: global fetch() is unavailable, replace "command": "npx" with the absolute path to a modern node + the absolute path to the installed bin.js:

{
  "mcpServers": {
    "squawk": {
      "command": "/usr/local/bin/node",
      "args": ["/absolute/path/to/node_modules/@squawk/mcp/dist/bin.js"]
    }
  }
}
Copy

The server logs [squawk-mcp] node <version> on <platform>/<arch> and the tool-module count to stderr on every startup so you can verify the right runtime is being used.

Example prompts

Once connected, the model can answer things like "what airspace is over KJFK at 4500 feet?", "give me the live METAR for KSFO and KOAK", "parse this route: KJFK DCT MERIT J60 MARTN DCT KLAX", or "look up the aircraft with ICAO hex AC82EC".

Standalone CLI

You can run the server directly without an MCP host to verify that it starts and responds to protocol messages:

npx @squawk/mcp
Copy

The binary speaks MCP over stdio, so it expects an MCP client on the other end of stdin/stdout. Logs go to stderr.

Programmatic use

Embed the server inside another MCP host or a custom transport:

import { createSquawkMcpServer } from '@squawk/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createSquawkMcpServer();
await server.connect(new StdioServerTransport());
Copy

Tool catalog

Tools are grouped by domain. Every tool returns both a human-readable text block and a structured JSON payload (structuredContent) so MCP clients with strict schemas can consume the results directly.

Geometry (@squawk/geo)

Airports (@squawk/airports + @squawk/airport-data)

Airspace (@squawk/airspace + @squawk/airspace-data)

Navaids (@squawk/navaids + @squawk/navaid-data)

Fixes (@squawk/fixes + @squawk/fix-data)

Airways (@squawk/airways + @squawk/airway-data)

Procedures (@squawk/procedures + @squawk/procedure-data)

Covers SIDs, STARs, and Instrument Approach Procedures (IAPs) from FAA CIFP.

ICAO aircraft registry (@squawk/icao-registry + @squawk/icao-registry-data)

The registry data (~40 MB raw) is loaded lazily on the first lookup so sessions that never need it do not pay the decompression cost.

Weather (@squawk/weather + @squawk/weather/fetch)

NOTAMs (@squawk/notams)

Flight plans (@squawk/flightplan)

Flight computer (@squawk/flight-math)

Selected E6B calculations: any operation that embeds a non-trivial constant, formula, or model (WMM2025, NOAA solar, compressible-flow pitot equations, etc.) is exposed; trivial unit math is left to the model itself.

Server diagnostics

Configuration

Notes

• The bundled datasets (airports, airspace, navaids, fixes, airways from FAA NASR; procedures from FAA CIFP) cover the contiguous United States plus the territories included in the respective FAA subscriptions. Outside the US the lookup tools will return empty results. Use get_dataset_status to confirm which NASR and CIFP cycles the running server is serving.
• Live weather tools issue HTTPS requests to https://aviationweather.gov/api/data/... (or the override above). They are the only tools that touch the network at invocation time; everything else operates against bundled snapshots in memory.
• The bundled snapshots are decompressed and indexed once when the server starts. Expect a few hundred milliseconds of startup time. The aircraft registration snapshot (the largest) is loaded lazily on the first lookup_aircraft_by_icao_hex call.