RT MCP Server

A TypeScript MCP server that provides read-only access to RT (Request Tracker) via the REST2 API. This Model Context Protocol (MCP) server allows Large Language Models to search for tickets, query ticket information, retrieve correspondence, download attachments, and explore ticket hierarchies.

Note: The maintained implementation is the TypeScript server in src/ (published to npm and packaged as MCPB). The python/ directory contains an earlier Python (FastMCP) prototype that is outdated and unmaintained — it lacks TicketSQL search, the get_ticketsql_grammar tool, and attachment-list pagination, and is excluded from the npm package.

Features

• Read-only access to RT tickets, correspondence, and attachments

• Token-based authentication via RT REST2 API

• Command-line & environment variable configuration

• Six main tools:

  • search_tickets - Search for tickets using RT's TicketSQL query language, with sorting and pagination

  • get_ticketsql_grammar - Get the TicketSQL field/operator reference for building queries

  • get_ticket - Retrieve complete ticket information

  • get_ticket_correspondence - Get ticket correspondence grouped by transaction with inline text and file metadata

  • get_attachment - Download any attachment by ID with base64-encoded content

  • get_ticket_hierarchy - Build ticket parent/child relationship trees

• STDIO transport for seamless integration with MCP clients

• TypeScript for type safety and better developer experience

• Easy deployment with npm/npx

Related MCP server: jama-mcp-server

Installation

Requirements

• Node.js ≥ v18.0.0

• RT authentication token (create via Settings > Auth Tokens in RT web interface)

MCP Clients

Using the Plugin (Recommended)

The plugin/ directory of this repository is a self-contained Claude Code plugin: the MCP server is bundled into a single dependency-free script (plugin/rt-mcp.cjs) that runs directly with node — no npm/npx download at runtime. The repository also doubles as its own plugin marketplace:

/plugin marketplace add msekoranja/rt-mcp
/plugin install rt@rt-mcp

The plugin reads your RT authentication token from the RT_API_TOKEN environment variable; set it in your shell profile. The RT server URL is set via the --url argument in plugin/.claude-plugin/plugin.json — edit it to point at your RT instance.

If the plugin is distributed through another marketplace (e.g. an organization-internal one), install it from there instead: /plugin install rt@<marketplace-name>.

After changing the TypeScript sources, regenerate the plugin bundle with npm run bundle.

Using Command Line

macOS/Linux:

claude mcp add rt -- npx -y rt-mcp-server --api-token YOUR_RT_TOKEN --url https://rt.example.com/REST/2.0

Windows:

claude mcp add rt -- cmd /c npx -y rt-mcp-server --api-token YOUR_RT_TOKEN --url https://rt.example.com/REST/2.0

Manual Configuration

Edit your Claude Code MCP configuration file and add:

{
  "mcpServers": {
    "rt": {
      "command": "npx",
      "args": [
        "-y",
        "rt-mcp-server",
        "--api-token",
        "YOUR_RT_TOKEN",
        "--url",
        "https://rt.example.com/REST/2.0"
      ]
    }
  }
}

Option 1: UI Method

1. Open Claude Desktop

2. Navigate to Settings → Developer → Edit Config

3. Add the RT MCP server configuration

Option 2: Configuration File

Edit claude_desktop_config.json (location varies by OS):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

macOS/Linux configuration:

{
  "mcpServers": {
    "rt": {
      "command": "npx",
      "args": [
        "-y",
        "rt-mcp-server",
        "--api-token",
        "YOUR_RT_TOKEN",
        "--url",
        "https://rt.example.com/REST/2.0"
      ]
    }
  }
}

Windows configuration:

{
  "mcpServers": {
    "rt": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "rt-mcp-server",
        "--api-token",
        "YOUR_RT_TOKEN",
        "--url",
        "https://rt.example.com/REST/2.0"
      ]
    }
  }
}

Restart Claude Desktop after saving.

Using Command Line (Recommended)

gemini mcp add rt npx -y rt-mcp-server --api-token YOUR_RT_TOKEN --url https://rt.example.com/REST/2.0

Manual Configuration

Edit the Gemini settings file at ~/.gemini/settings.json and add the RT MCP server to the mcpServers object:

{
  "mcpServers": {
    "rt": {
      "command": "npx",
      "args": [
        "-y",
        "rt-mcp-server",
        "--api-token",
        "YOUR_RT_TOKEN",
        "--url",
        "https://rt.example.com/REST/2.0"
      ]
    }
  }
}

Using Command Line (Recommended)

codex mcp add rt npx -y rt-mcp-server --api-token YOUR_RT_TOKEN --url https://rt.example.com/REST/2.0

Manual Configuration

Add the RT MCP server to your OpenAI Codex configuration using TOML format:

[mcp_servers.rt]
command = "npx"
args = [
  "-y",
  "rt-mcp-server",
  "--api-token",
  "YOUR_RT_TOKEN",
  "--url",
  "https://rt.example.com/REST/2.0"
]

Use the MCP toolkit to integrate RT:

from langchain_mcp import MCPToolkit

rt_toolkit = MCPToolkit(
    server_params={
        "command": "npx",
        "args": [
            "-y",
            "rt-mcp-server",
            "--api-token",
            "YOUR_RT_TOKEN",
            "--url",
            "https://rt.example.com/REST/2.0"
        ]
    }
)

tools = rt_toolkit.get_tools()

Local Development Installation

If you want to develop or modify the server:

# Clone the repository
git clone <repository-url>
cd rt-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Test it
node dist/index.js --api-token "YOUR_RT_TOKEN" --url "https://rt.example.com/REST/2.0"

Configuration

The server supports configuration via command-line arguments or environment variables.

Command-Line Arguments (Recommended)

• --api-token - Your RT authentication token

• --url - RT server base URL (required)

Environment Variables (Alternative)

• RT_TOKEN - Your RT authentication token

• RT_BASE_URL - RT server base URL

Priority: Command-line arguments override environment variables.

Usage with MCP Clients

After installing the RT MCP server in your preferred MCP client (see Installation section above), you can interact with RT tickets using natural language.

Usage Examples

Example 1: Searching for Tickets

Ask your MCP-enabled LLM:

"Show me my last 10 tickets"

The LLM will use search_tickets(query="Owner = '__CurrentUser__'", orderby="Created", order="DESC", per_page=10) to find your most recent tickets and display a summary of results. Queries use RT's TicketSQL language (e.g. Created > '2026-06-01' AND Owner = 'jsmith'); usernames follow the jsmith pattern, and __CurrentUser__ resolves to the authenticated token's user.

Example 2: Checking Ticket Status

Ask your MCP-enabled LLM:

"What is the status of RT ticket 12345?"

The LLM will use get_ticket(12345) to fetch the ticket details and report the status, owner, priority, and other relevant information.

Example 3: Reading Ticket Correspondence

Ask your MCP-enabled LLM:

"Show me all the comments and correspondence from RT ticket 67890"

The LLM will use get_ticket_correspondence(67890) to retrieve all correspondence grouped by transaction, including inline text messages and file attachment metadata.

Example 4: Downloading Attachments

Ask your MCP-enabled LLM:

"Download the PDF receipt from RT ticket 67890"

The LLM will use get_ticket_correspondence(67890) to find attachment IDs, then get_attachment(attachment_id) to download the specific file with base64-encoded content.

Example 5: Exploring Ticket Hierarchies

Ask your MCP-enabled LLM:

"Show me the parent and child tickets for RT ticket 54321"

The LLM will use get_ticket_hierarchy(54321, recursive=True) to build the complete relationship tree showing all related tickets.

Available Tools

search_tickets(query, orderby?, order?, per_page?, page?, fields?, subfields?)

Searches for tickets using RT's TicketSQL query language, with optional sorting and pagination.

Breaking change (since simple-search removal): query is now TicketSQL, not free-text. A keyword search like "database error" must be written as Subject LIKE 'database error' (or use Content LIKE '...'). Call get_ticketsql_grammar for the full syntax.

Parameters:

• query - TicketSQL query string (e.g., "Created > '2026-06-01' AND Owner = 'jsmith'"). Use "id > 0" to match all tickets.

• orderby - Field to sort by. One of: id, Created, LastUpdated, Started, Resolved, Due, Told, Priority, Subject, Status, Queue, Owner.

• order - ASC or DESC (defaults to DESC when orderby is set).

• per_page - Results per page (default 20, max 100).

• page - Page number (default 1).

• fields - Comma-separated list of extra fields to include (e.g., "Priority,Requestor").

• subfields - Expand nested objects inline, e.g. {"Owner":"Name,EmailAddress","Queue":"Name"}.

Example (my last 10 tickets):

{
  "query": "Owner = '__CurrentUser__'",
  "orderby": "Created",
  "order": "DESC",
  "per_page": 10
}

Returns:

{
  "total": 45,
  "count": 10,
  "per_page": 10,
  "page": 1,
  "tickets": [
    {
      "id": 261687,
      "subject": "Database connection error on production",
      "status": "open",
      "queue": "Engineering",
      "owner": "jsmith",
      "created": "2026-06-29T10:30:00Z"
    }
  ]
}

get_ticketsql_grammar()

Returns the TicketSQL query language reference (fields, operators, date literals, and examples) for building search_tickets queries. Takes no parameters.

get_ticket(ticket_id: number)

Retrieves complete ticket information including:

• Basic info: ID, type, subject, status, queue

• People: owner, creator, requestors, CC, AdminCC

• Dates: created, started, resolved, last updated

• Time tracking: worked, estimated, left

Example:

{
  "ticket_id": 12345
}

Returns:

{
  "id": 12345,
  "subject": "Example ticket",
  "status": "open",
  "queue": "General",
  "owner": "username",
  "creator": "requester@example.com",
  "created": "2024-01-15T10:30:00Z"
}

get_ticket_correspondence(ticket_id: number)

Retrieves all correspondence from a ticket, grouped by transaction. Each transaction may contain:

• Inline text messages (user's typed message)

• File attachments (with metadata only)

Example:

{
  "ticket_id": 12345
}

Returns:

{
  "ticket_id": 12345,
  "total_attachments": 5,
  "correspondence": [
    {
      "transaction_id": "100",
      "creator": "jsmith",
      "created": "2024-01-15T10:35:00Z",
      "message": "This is the user's typed message...",
      "attachments": [
        {
          "id": 67890,
          "filename": "document.pdf",
          "content_type": "application/pdf",
          "size": "42.0 KB"
        }
      ]
    }
  ]
}

get_attachment(attachment_id: number)

Downloads a specific attachment by ID, returning base64-encoded content for any file type.

Example:

{
  "attachment_id": 67890
}

Returns:

{
  "attachment_id": 67890,
  "filename": "document.pdf",
  "content_type": "application/pdf",
  "size": "42.0 KB",
  "content_base64": "JVBERi0xLjQK...",
  "created": "2024-01-15T10:35:00Z",
  "creator": "jsmith"
}

get_ticket_hierarchy(ticket_id: number, recursive?: boolean)

Retrieves the parent/child relationship tree for a ticket.

Parameters:

• ticket_id - The RT ticket ID

• recursive - If true, fetches complete tree; if false, only immediate relationships (default: true)

Example:

{
  "ticket_id": 12345,
  "recursive": true
}

Returns:

{
  "ticket_id": 12345,
  "recursive": true,
  "tickets_fetched": 10,
  "hierarchy": {
    "id": 12345,
    "subject": "Main ticket",
    "status": "open",
    "parents": {
      "12340": {
        "id": 12340,
        "subject": "Parent ticket"
      }
    },
    "children": {
      "12350": {
        "id": 12350,
        "subject": "Child ticket"
      }
    }
  }
}

How It Works

1. Configuration: Parses command-line arguments (or reads environment variables) for RT URL and authentication token

2. Authentication: Uses token-based auth with RT REST2 API for all requests

3. HTTP Client: Uses native fetch API for async HTTP requests to RT REST2 API

4. Error Handling: Returns error information as objects rather than throwing exceptions

5. MCP Protocol: Implements MCP server using @modelcontextprotocol/sdk with STDIO transport

6. Type Safety: Full TypeScript type checking for reliability

API Endpoints Used

The server interacts with these RT REST2 endpoints:

• GET /tickets?query={ticketsql}&orderby={field}&order={ASC|DESC}&per_page={n}&page={n}&fields={...} - Search tickets using TicketSQL

• GET /ticket/{id} - Retrieve ticket information

• GET /ticket/{id}/attachments - List all attachments for a ticket

• GET /attachment/{id} - Retrieve individual attachment content (base64-encoded)

Documentation

• RT REST2 API Documentation - Official RT REST2 API reference

• Model Context Protocol - MCP specification

Development

Building

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Watch mode (auto-rebuild on changes)
npm run dev

Project Structure

rt-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (generated)
├── .claude-plugin/
│   └── marketplace.json  # Plugin marketplace catalog (repo is its own marketplace)
├── plugin/               # Claude Code plugin (self-contained)
│   ├── .claude-plugin/
│   │   └── plugin.json   # Plugin manifest
│   ├── rt-mcp.cjs        # Bundled MCP server (generated by `npm run bundle`, intentionally committed)
│   └── README.md         # Plugin documentation
├── package.json          # Node.js dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .gitignore            # Git ignore rules
├── README.md             # This file
└── CLAUDE.md             # Guide for Claude Code

Running Tests

# Run the built server with test credentials
node dist/index.js --api-token "test-token" --url "https://rt.example.com/REST/2.0"

Common Workflows

Reading Ticket Information

Simply ask Claude in natural language:

• "What's the status of RT ticket 12345?"

• "Who is assigned to ticket 67890?"

• "When was ticket 11111 created and last updated?"

• "Show me the custom fields for ticket 22222"

Analyzing Ticket Discussions

Ask Claude to summarize or analyze:

• "Read all comments from RT ticket 33333 and summarize the issue"

• "What are the main discussion points in ticket 44444?"

• "Extract action items from the conversation in ticket 55555"

• "Translate the technical discussion in ticket 66666 to non-technical language"

Batch Operations

Ask Claude to process multiple tickets:

• "Compare the status of tickets 100, 101, and 102"

• "Show me a table of ticket 200, 201, 202 with status, owner, and priority"

• "Check if any of tickets 300-305 mention the word 'urgent' in their attachments"

Limitations

• Read-only: No ticket creation, updates, or deletion capabilities

• TicketSQL only: Search uses RT's TicketSQL language (no free-text keyword mode); use get_ticketsql_grammar for syntax

• Single sort field: orderby accepts one field at a time (no multi-field sorting)

• No transaction history: Does not expose complete ticket history/transactions (only correspondence)

• Single ticket at a time: Each tool call fetches one ticket (LLM can call multiple times for batch operations)

• File size: Large attachments may take time to download depending on RT server performance

• Search result limit: Maximum 100 tickets per page (RT API limitation); use page to paginate

Troubleshooting

Module Not Found Error

If you see module errors during build:

# Make sure dependencies are installed
npm install
# Rebuild the project
npm run build

Authentication Errors

If you see HTTP 401 or 403 errors:

• Verify your RT token is correct

• Check the token hasn't expired

• Ensure your RT user has permissions to access tickets

• Verify the RT server URL is correct

Connection Errors

If you see connection timeout or refused errors:

• Check the RT server URL (should include /REST/2.0)

• Verify the server is accessible from your network

• Ensure HTTPS is being used

TypeScript Build Errors

If you encounter TypeScript compilation errors:

• Check that you're using Node.js ≥18.0.0

• Ensure all dependencies are installed: npm install

• Try cleaning and rebuilding: npm run clean && npm run build

Security Notes

• Store RT_TOKEN securely (environment variables, secrets manager, etc.)

• Never commit tokens to version control (.gitignore excludes token.txt and .env files)

• The server will fail fast if RT_TOKEN is not provided

• All communication with RT should use HTTPS

• Command-line tokens may be visible in process lists - prefer environment variables in production

Contributing

When extending this server:

• Follow TypeScript best practices

• Use async/await pattern consistently

• Return error objects instead of throwing exceptions

• Update tool schemas for new functionality

• Test with actual RT instance before committing

• Run npm run build after making changes