RT MCP Server

Model Context Protocol (MCP) server for Request Tracker REST2 API built with fastmcp.

Features

• ✅ Comprehensive RT REST2 API coverage (85+ tools planned)

• ✅ Tag-based tool filtering (resource type, operation, permission level)

• ✅ Advanced fastmcp features (dependency injection, lifespan, Context)

• ✅ Environment variable configuration

• ✅ Type-safe with Pydantic models

• ✅ Async/await throughout

• ✅ Production-ready error handling

Related MCP server: RT MCP Server

Quick Start

Installation

# Clone or navigate to the repository
cd rt-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# For development
pip install -e ".[dev]"

Configuration

Create a .env file based on .env.example:

cp .env.example .env

Edit .env with your RT credentials:

RT_URL=https://your-rt-server.com
RT_TOKEN=your_token_here
# OR
# RT_USER=username
# RT_PASSWORD=password

Running the Server

The server uses Streamable HTTP transport (listening on port 8000 by default).

# Optional: Configure host/port
export HOST=0.0.0.0
export PORT=8000

# Run directly
python -m rt_mcp.server

# Or use the installed command
rt-mcp

Docker 🐳

# Build and start
docker compose up -d --build

The server will be available at http://localhost:8000/mcp.

Available Tools

Total: 75 tools + 4 resources - Complete RT REST2 API coverage!

Ticket Operations (15 tools, tags: tickets)

• create_ticket, get_ticket, update_ticket, delete_ticket

• search_tickets, correspond_ticket, comment_ticket

• take_ticket, steal_ticket, untake_ticket

• merge_tickets, link_tickets

• get_ticket_history, get_ticket_attachments

Queue Operations (8 tools, tags: queues)

• list_queues, get_queue, create_queue, update_queue

• search_queues, disable_queue, enable_queue

User Operations (11 tools, tags: users)

• list_users, get_user, get_current_user

• create_user, update_user, search_users

• disable_user, enable_user

• grant_privilege, revoke_privilege

Group Operations (8 tools, tags: groups)

• list_groups, get_group, create_group, update_group

• delete_group, search_groups

• add_group_member, remove_group_member

Asset Operations (6 tools, tags: assets)

• list_assets, get_asset, create_asset

• update_asset, delete_asset, search_assets

Transaction Operations (3 tools, tags: transactions)

• get_transaction, list_transactions, search_transactions

Attachment Operations (3 tools, tags: attachments)

• get_attachment, get_attachment_content, upload_attachment

Catalog Operations (6 tools, tags: catalogs)

• list_catalogs, get_catalog, create_catalog

• update_catalog, delete_catalog, search_catalogs

Custom Field Operations (6 tools, tags: custom-fields)

• list_custom_fields, get_custom_field, create_custom_field

• update_custom_field, delete_custom_field, search_custom_fields

Custom Role Operations (6 tools, tags: custom-roles)

• list_custom_roles, get_custom_role, create_custom_role

• update_custom_role, delete_custom_role, search_custom_roles

Advanced Search (3 tools, tags: search)

• search_all - Search across all RT objects

• bulk_update - Update multiple objects with progress reporting

• advanced_ticket_search - Auto-paginated ticket search

Resources (4 resources)

• rt://queues/list - List all queues

• rt://custom-fields/list - List all custom fields

• rt://user/current - Current authenticated user

• rt://server/info - RT server information

Tag Taxonomy

Tools are organized with multi-dimensional tags:

Resource Type

• tickets - Ticket operations

• queues - Queue management

• users - User operations

• groups - Group management

• assets - Asset tracking

• catalogs - Catalog management

• transactions - Transaction history

• attachments - File operations

• custom-fields - Custom field management

• custom-roles - Custom role operations

Operation Type

• read - Safe GET operations

• write - State-changing operations

• delete - Destructive operations

• search - Search/query operations

Permission Level

• basic - Common user operations

• power-user - Advanced operations

• admin - Administrative functions

Using with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

Since the server runs via Streamable HTTP / SSE, configuring it is simple:

{
  "mcpServers": {
    "rt": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Note: Ensure the server is running (locally or via Docker) before connecting Claude Desktop.

If you prefer to have Claude Desktop manage the process (local only):

{
  "mcpServers": {
    "rt": {
      "command": "/path/to/rt-mcp/venv/bin/python",
      "args": ["-m", "rt_mcp.server"],
      "env": {
        "RT_URL": "https://your-rt-server.com",
        "RT_TOKEN": "your_token_here"
      }
    }
  }
}

Development

Project Structure

src/rt_mcp/
├── __init__.py
├── server.py              # FastMCP server with lifespan
├── config.py              # Pydantic settings (env vars)
├── client.py              # RT REST2 API client (httpx)
├── dependencies.py        # Dependency injection providers
├── models/
│   ├── common.py          # Base Pydantic models
│   └── ...
├── tools/
│   ├── tickets.py         # Ticket tools
│   └── ...                # More tool modules coming
├── resources/
│   └── ...                # MCP resources
└── utils/
    ├── errors.py          # Exception hierarchy
    └── helpers.py

Running Tests

pytest
pytest --cov=rt_mcp

Code Quality

# Format
black src tests

# Lint
ruff check src tests

# Type check
mypy src

Architecture

Dependency Injection

The server uses fastmcp's dependency injection system:

from fastmcp import Context
from fastmcp.dependencies import Depends
from rt_mcp.dependencies import get_rt_client

@mcp.tool()
async def my_tool(
    ticket_id: int,
    ctx: Context,  # Injected MCP context
    client = Depends(get_rt_client)  # Injected RT client
) -> dict:
    await ctx.info("Processing...")
    return await client.get_ticket(ticket_id)

Lifespan Management

Server validates RT connection on startup:

@asynccontextmanager
async def lifespan(mcp):
    # Startup: validate connection
    config = RTConfig()
    async with RTClient(config) as client:
        await client.validate_connection()

    yield

    # Shutdown: cleanup

Error Handling

Custom exception hierarchy for RT errors:

• RTAuthenticationError (401)

• RTAuthorizationError (403)

• RTNotFoundError (404)

• RTValidationError (422)

• RTConflictError (409/412)

• RTNetworkError (network/timeout)

• RTAPIError (generic)

Roadmap

Phase 1: Foundation ✅

• Project structure

• Configuration with pydantic-settings

• RT client with httpx

• Error handling

• Dependency injection

• Server initialization

Phase 2: Core Tools ✅

• Complete ticket tools (15 total)

• Queue tools (8)

• User tools (11)

• MCP resources (4 resources)

Phase 3: Extended Tools

• Group tools (8)

• Asset tools (10)

• Transaction tools (5)

• Attachment tools (5)

Phase 4: Advanced Tools

• Catalog tools (6)

• Custom field tools (8)

• Custom role tools (6)

• Search tools (3)

• Resources for reference data

Phase 5: Polish

• Comprehensive tests (>80% coverage)

• Complete documentation

• Performance optimization

• CI/CD pipeline

Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure code quality checks pass

5. Submit a pull request

License

MIT License

Links

• Request Tracker Documentation

• RT REST2 API Reference

• fastmcp Documentation

• Model Context Protocol