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

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 ✅

• [x] Project structure
• [x] Configuration with pydantic-settings
• [x] RT client with httpx
• [x] Error handling
• [x] Dependency injection
• [x] Server initialization

Phase 2: Core Tools ✅

• [x] Complete ticket tools (15 total)
• [x] Queue tools (8)
• [x] User tools (11)
• [x] 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