DIMO MCP Server

An MCP (Model Context Protocol) server that provides seamless access to the DIMO Network APIs, enabling AI assistants to query vehicle data, execute vehicle commands, decode VINs, create verifiable credentials, and interact with the DIMO ecosystem.

Overview

This server acts as a bridge between AI assistants and DIMO's vehicle data network, providing:

• Direct access to DIMO's GraphQL APIs (Identity and Telemetry)

• Automatic JWT token management for authenticated endpoints

• Vehicle ownership validation with fleet mode support

• VIN decoding and vehicle information lookup

• Vehicle command execution (doors, charging)

• Verifiable credential creation (VIN credentials)

• Vehicle NFT minting using DIMO transactions SDK

• Schema introspection for both APIs

• OAuth authentication flow management

Architecture

The server is built with a modular architecture split across focused tool categories:

• Server Identity Tools (server-identity.ts) - Authentication, OAuth flows, and vehicle access checking

• Vehicle Data Tools (vehicle-data.ts) - GraphQL queries for identity and telemetry APIs with schema introspection

• Vehicle Commands Tools (vehicle-commands.ts) - Door lock/unlock and charging start/stop commands

• Vehicle Minting Tools (vehicle-minting.ts) - Vehicle NFT minting using DIMO transactions SDK

• Utilities Tools (utilities.ts) - VIN decoding, vehicle search, and attestation creation

Quick Start

Prerequisites

• Node.js 18 or higher (or Bun runtime)

• DIMO Developer License from DIMO Developer Console

• Valid API credentials (client ID, domain, and private key)

Installation

Configuration

Set up your environment variables:

MCP Client Setup (Claude Desktop)

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Available Tools

🆔 Server Identity & Authentication

check_vehicle_access_status

Check current vehicle access status and authentication state.

ALWAYS call this tool first to understand what vehicles are available before attempting any vehicle operations. Shows which vehicles have granted access to their data.

Example:

init_oauth

Initialize OAuth authentication flow with automatic callback handling.

Starts a local server and opens OAuth URL for user authentication.

Parameters:

• port (optional): Local server port (default: 3333)

Example:

generate_vehicle_data_sharing_url

Generate URL for users to share vehicle data with this developer license.

Parameters:

• permissionTemplateId (optional): Permission template ID (default: 1)

📊 Vehicle Data & Schema

identity_introspect

Introspect the DIMO Identity GraphQL schema.

ALWAYS call this tool first before using identity_query to understand available fields and types.

identity_query

Query the DIMO Identity GraphQL API for public data.

Prerequisites: Must call identity_introspect first to understand schema structure.

Parameters:

• query: GraphQL query string

• variables: Query variables object

Example:

telemetry_introspect

Introspect the DIMO Telemetry GraphQL schema.

ALWAYS call this tool first before using telemetry_query to understand available fields and types.

telemetry_query

Query vehicle telemetry data (requires authentication and vehicle access).

Prerequisites:

• Must call telemetry_introspect first to understand schema structure

• Vehicle must be shared with this developer license

• User must be authenticated

Parameters:

• query: GraphQL query string

• variables: Query variables object (must include tokenId)

Example:

🚗 Vehicle Commands

All vehicle commands require:

• Vehicle shared with this developer license

• User authentication

• Vehicle ownership (unless FLEET_MODE=true)

lock_doors

Lock vehicle doors.

Parameters:

• tokenId: Vehicle token ID

unlock_doors

Unlock vehicle doors.

Parameters:

• tokenId: Vehicle token ID

start_charge

Start vehicle charging (electric/hybrid vehicles only).

Parameters:

• tokenId: Vehicle token ID

stop_charge

Stop vehicle charging (electric/hybrid vehicles only).

Parameters:

• tokenId: Vehicle token ID

🔧 Utilities

vin_decode

Decode a VIN to get vehicle specifications.

Parameters:

• vin: Vehicle Identification Number

• countryCode (optional): Country code (default: "USA")

Example:

search_vehicles

Search DIMO's vehicle definition database.

Parameters:

• query (optional): Free-text search query

• make (optional): Vehicle make

• model (optional): Vehicle model

• year (optional): Vehicle year

Example:

attestation_create

Create verifiable credentials for vehicles.

Prerequisites:

• Vehicle must be shared with this developer license

• User must be authenticated

• Vehicle ownership required (unless FLEET_MODE=true)

Parameters:

• tokenId: Vehicle token ID

• type: Credential type ("vin")

• force (optional): Force creation even if exists (default: false)

🚀 Vehicle Minting

initialize_kernel_signer

Initialize the DIMO KernelSigner for vehicle minting transactions.

Sets up the blockchain signer with passkey authentication for minting vehicle NFTs.

Parameters:

• rpcUrl: RPC URL for the blockchain network

• bundlerUrl: Bundler URL for transaction bundling

• paymasterUrl: Paymaster URL for gasless transactions

• environment: Environment ('dev' or 'prod', default: 'dev')

• subOrganizationId: Sub-organization ID for the signer

• walletAddress: Wallet address for the signer

• rpId: Relying Party ID for passkey authentication

Example:

mint_vehicle

Mint a new vehicle NFT using the DIMO transactions SDK.

Prerequisites:

• KernelSigner must be initialized via initialize_kernel_signer

Parameters:

• make: Vehicle make (e.g., 'Toyota', 'Ford')

• model: Vehicle model (e.g., 'Camry', 'F-150')

• year: Vehicle year (e.g., 2023)

• vin (optional): Vehicle VIN (will be decoded if provided)

• deviceDefinition (optional): Device definition object

Example:

get_minting_status

Check the status of the KernelSigner and minting capabilities.

Returns information about whether the signer is initialized and ready for vehicle minting.

Example:

Authentication & Authorization

Two-Tier Authentication System

1. Developer JWT (System-Level)

• Purpose: Authenticate the MCP server itself with DIMO APIs

• Required for: All API calls, VIN decoding, vehicle search

• Configuration: DIMO_CLIENT_ID, DIMO_DOMAIN, DIMO_PRIVATE_KEY

2. User OAuth (User-Level)

• Purpose: Users grant permission to access their specific vehicle data

• Required for: Vehicle telemetry, commands, attestations

• Process: Use init_oauth tool to start authentication flow

Fleet Mode

Set FLEET_MODE=true to skip vehicle ownership checks, allowing operation on any vehicle shared with the developer license.

Environment Variables

Required

Optional

Usage Workflow

Recommended Tool Call Sequence

1. check_vehicle_access_status - See what vehicles are available

2. identity_introspect / telemetry_introspect - Understand schema structure

3. init_oauth (if needed) - Authenticate user for vehicle access

4. identity_query / telemetry_query - Query with proper schema knowledge

5. Vehicle commands/operations - Execute actions on known vehicles

Example: Complete Vehicle Data Query

Error Handling

The server provides intelligent error detection and guidance:

Schema Errors

When GraphQL queries fail due to unknown fields, the server detects this and provides specific guidance:

Authentication Errors

Clear messages guide users through the authentication process:

Ownership Errors

Fleet mode and ownership validation provide appropriate access control:

Development

Project Structure

Development Commands

Adding New Tools

1. Create tool in appropriate module (tools/)

2. Use shared validation helpers from command-helpers.ts

3. Follow consistent return format:

   return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };

Security Features

• Input Validation: All inputs validated using Zod schemas

• Authentication Required: Protected endpoints require proper authentication

• Ownership Validation: Vehicle operations validate ownership (unless fleet mode)

• JWT Token Management: Automatic token refresh and validation

• Error Sanitization: Safe error messages without sensitive data exposure

Troubleshooting

Common Issues

1. Authentication Failed

Solution: Ensure DIMO_DOMAIN and DIMO_PRIVATE_KEY are set correctly.

2. Vehicle Access Denied

Solution: Either enable FLEET_MODE=true or ensure the authenticated user owns the vehicle.

3. Schema Errors

Solution: Call the appropriate introspection tool (identity_introspect or telemetry_introspect) first.

4. No Vehicle Access

Solution: Use init_oauth to authenticate and share vehicles through the DIMO app.

Debug Logging

The server provides structured JSON logging for debugging:

API Reference

Vehicle Data APIs

• Identity API: https://identity-api.dimo.zone/query - Public vehicle and device information

• Telemetry API: https://telemetry-api.dimo.zone/query - Real-time and historical vehicle data

• Devices API: https://devices-api.dimo.zone - Vehicle command execution

Supported Vehicle Commands

• Door Control: Lock/unlock doors on compatible vehicles

• Charging Control: Start/stop charging on electric/hybrid vehicles

• Future: Additional commands as supported by DIMO network

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes following the existing patterns

4. Test your changes

5. Submit a pull request

License

MIT License - see LICENSE file for details.

Links

• DIMO Network

• DIMO Developer Console

• DIMO Documentation

• Model Context Protocol