@trackunit/mcp-server

GraphQL MCP Server

Model Context Protocol (MCP) server for Trackunit's GQL API with schema introspection, query validation, and execution capabilities.

Overview

This MCP server provides three complementary tools for working with Trackunit's GQL API:

• introspect-schema - Discover available fields, types, and operations
• validate-query - Test query syntax without authentication
• execute-query - Execute queries and get real data

Tools

introspect-schema

Explore the Trackunit's GQL schema by searching for fields and types. Generates sample queries.

Parameters:

• keywords - Search terms (e.g. ["user", "asset", "location"])
• operationType - "query", "mutation", or "subscription" (default: "query")
• generateQuery - Auto-generate sample query (default: true)

validate-query

Test if a GraphQL query is valid by sending it without authentication. Returns validation errors or confirms the query is correct.

Parameters:

• query - GraphQL query to validate
• variables - Optional query variables
• useIntrospection - Load schema for better error suggestions (default: true)

Logic: Valid queries return UNAUTHENTICATED errors. Invalid queries return GRAPHQL_VALIDATION_FAILED errors.

execute-query

Execute GraphQL queries against the authenticated endpoint. Requires authentication.

Parameters:

• query - GraphQL query to execute
• variables - Optional query variables

Setup

Environment Variables

• TU_ENV - Environment (PROD, STAGE, DEV, default: PROD)
• TU_TOKEN - Optional: Use existing token instead of OAuth flow

Running

Standalone:

# Build and run
nx build mcp-server
./apps/mcp-server/run.sh

# Or with environment
TU_ENV=STAGE ./apps/mcp-server/run.sh

With Cursor: Add to .cursor/mcp.json:

{
  "mcpServers": {
    "trackunit-mcp": {
      "command": "./apps/mcp-server/run.sh"
    }
  }
}

Authentication

The server uses OAuth device flow for Trackunit's GraphQL API:

• execute-query requires authentication
• validate-query intentionally omits authentication for validation testing
• introspect-schema does not require authentication
• Automatic token refresh and retry on auth failures

For more info and a full guide on Iris App SDK Development, please visit our Developer Hub.

Development

At this point this library is only developed by Trackunit Employees.
For development related information see the development readme.

Trackunit

This package was developed by Trackunit ApS. Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.