TDX MCP Server

A Model Context Protocol (MCP) server that wraps the TeamDynamix (TDX) REST API, enabling AI-assisted IT service management through Claude Desktop, Claude Code, and other MCP clients.

This server exposes 41 tools across 9 domains — tickets, assets, CMDB, knowledge base, people, projects, accounts, groups, and custom attributes — allowing natural language interaction with your TDX instance.

Quick Start

macOS

1. Double-click setup-mac.command
2. Enter your BEID, Web Services Key, and App ID when prompted
3. Restart Claude Desktop

Windows

1. Double-click setup-windows.bat
2. Enter your BEID, Web Services Key, and App ID when prompted
3. Restart Claude Desktop

Manual Setup

npm install
npm run build

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "tdx": {
      "command": "node",
      "args": ["/path/to/TDX-MCP/dist/index.js"],
      "env": {
        "TDX_BASE_URL": "https://yourorg.teamdynamix.com/TDWebApi/api",
        "TDX_BEID": "your-beid-guid",
        "TDX_WEB_SERVICES_KEY": "your-web-services-key-guid",
        "TDX_APP_ID": "123"
      }
    }
  }
}

Authentication

This server uses TDX admin token authentication (POST /auth/loginadmin) with a BEID and Web Services Key — not username/password. These are API-specific service account keys that are:

• Not tied to SSO or any user's credentials
• Generated in TDAdmin > Organization Details > API Settings
• Revocable independently without affecting user accounts
• Accessible to any admin with the "Add BE Administrators" permission

Tokens are fetched lazily on the first tool call and auto-refreshed after 23 hours (1-hour buffer before the 24-hour TDX expiry).

Environment Variables

Tools (41)

All tools that operate within an application accept an optional appId parameter to override the default from TDX_APP_ID.

Tickets (9 tools)

Assets (7 tools)

CMDB / Configuration Items (7 tools)

Knowledge Base (5 tools)

People (4 tools)

These tools do not require an appId.

Projects (4 tools)

These tools do not require an appId.

Accounts (2 tools)

Groups (2 tools)

Custom Attributes (1 tool)

Common componentId values for tdx-attributes-get: 9 = Ticket, 27 = Asset, 63 = CI, 39 = KB Article, 2 = Project.

Example Usage

Once configured, you can use natural language in Claude Desktop or Claude Code:

• "Search for open tickets assigned to me"
• "Get ticket #12345 and show me the comments"
• "Look up john.doe@example.com in TDX"
• "Search the knowledge base for VPN setup instructions"
• "Find all assets in the IT department"
• "Create a ticket for a new software request"

TDX API Documentation

• TeamDynamix Web API Reference
• API Authentication Guide

Project Structure

TDX-MCP/
  package.json
  tsconfig.json
  .env.example
  setup-mac.command        # macOS setup wizard
  setup-windows.bat        # Windows setup launcher
  setup-windows.ps1        # Windows setup wizard
  src/
    index.ts               # Entry point
    config.ts              # Environment variable loading
    auth.ts                # Admin token auth with auto-refresh
    tdx-client.ts          # Shared HTTP client
    tools/
      tickets.ts           # 9 ticket tools
      assets.ts            # 7 asset tools
      cmdb.ts              # 7 CMDB/CI tools
      kb.ts                # 5 knowledge base tools
      people.ts            # 4 people tools
      projects.ts          # 4 project tools
      accounts.ts          # 2 account tools
      groups.ts            # 2 group tools
      attributes.ts        # 1 custom attributes tool

Created by University of Montana IT with Claude