How do I use MCP IT Help Desk?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP IT Help Desk WiFi connection keeps dropping, please help." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP IT Help Desk

by minasenel

Overview Schema Related Servers Score Discussions

Python

Remote

🤖 MCP IT Help Desk

Python MCP Protocol Fast Agent License: MIT

AI-powered IT support: understands issues (TR/EN), suggests fixes, and routes to the right experts. Experts are stored in Django DB.

✨ Features

AI-Powered Classification (100% LLM): Turkish + English via Gemini; no heuristics
Auto-Solutions: Common hardware/software/network fixes for non-critical cases
Smart Expert Assignment: Availability + expertise + load consideration
Modern Web UI: Real-time chat via Flask + Socket.IO + Tailwind
MCP Tools: Add/process issues, AI try-solve, assign experts

🧭 Table of Contents

🔧 MCP Tools
🚀 Quick Start
🧱 Architecture
🗂️ File Structure
📖 Comprehensive Documentation
⚙️ Advanced Configuration
🧪 Usage Examples
🧠 Design Philosophy
🤝 Contributing & Support

🔧 MCP Tools

Tool	Purpose	Inputs	Output
`add_issue`	Create a new ticket with normalized fields and timestamps	`employee_id, description, category, subcategory, priority`	`Issue created: ISSnnn`
`ai_try_solve`	Attempt auto-resolution for common issues (non-critical)	`description, category, subcategory, priority`	Solution text or suggestion to assign expert
`assign_expert`	Classify description and pick best available expert	`description`	`Assigned expert: T00x - Name (category/subcategory)`
`process_issues`	Batch normalize + auto-solve + assign/queue	none	Summary: closed_by_ai, assigned/queued, skipped

👩‍💻 Expert Data Format (Django DB)

Field	Type	Example	Notes
`id`	string (pk)	`T001`	Human-friendly ID
`name`	string	`Elif Hanım, Ağ Uzmanı`	Display name
`expertise`	JSON/list	`["network","vpn"]`	Tags matched by classifier
`contact`	string	`elif@example.com`	Optional
`availability`	boolean	`true`	Considered for assignment
`current_load`	integer	`0`	Incremented on assignment

🚀 Quick Start

Prerequisites

Python 3.11+
uv (recommended)
Gemini API key (required): set GEMINI_API_KEY or GOOGLE_API_KEY

Install dependencies

uv sync

🔥 Most Important: Start Project (2 terminals)

Terminal 1 — start Django API (port 8000):

cd django_api_service
python3 manage.py runserver 8000

Terminal 2 — start Web UI (Flask + Socket.IO):

cd ..  # back to project root (mcp-it-helpdesk)
uv run python start_web_agent.py

Set up Django (migrations + import experts)

cd django_api_service
uv run python manage.py makemigrations
uv run python manage.py migrate
uv run python import_experts.py  # imports tech_experts.json into DB

Run services

# MCP (via Fast Agent)
uv run fast-agent go --stdio "uv run python main.py"

# Django API (serves at http://localhost:8000; root "/" returns 404 by design)
uv run python django_api_service/manage.py runserver
# health check: http://localhost:8000/api/health/

# Web UI (Flask, serves at http://localhost:5001)
uv run python web_agent.py
# open http://localhost:5001

Notes:

API routes live under /api/ (e.g., /api/health/, /api/issues/). The root / returns 404 by design.
The web frontend at http://localhost:5001 calls the API at http://localhost:8000 by default.

🧱 Architecture

Web UI (Flask/Socket.IO)         Django API (REST + ORM)         MCP Server (main.py)
         │                                │                               │
         │  create/assign issues (HTTP)   │                               │
         └──────────────► /api/issues/ ───┼──────────┐                    │
                                          │          │                    │
                                          ▼          │                    │
                                  SQLite (Issues, Experts)                │
                                                     ▲                    │
                                                     └── load experts ◄───┘

🗂️ File Structure

mcp-it-helpdesk/
├─ main.py                     # MCP server with tools
├─ problems.txt                # Legacy issue store (MCP-only)
├─ tech_experts.json           # Legacy sample; data is stored in Django DB
├─ web_agent.py                # Flask web chat
├─ templates/index.html        # Web UI
├─ django_api_service/
│  ├─ api/settings.py          # Django settings
│  ├─ manage.py
│  └─ issues/
│     ├─ models.py             # Issue, Expert models
│     ├─ serializers.py        # Validation + Gemini integration
│     ├─ views.py              # REST endpoints and actions
│     └─ migrations/           # Django migrations
└─ docs/images/                # (add your screenshots/diagrams here)

📖 Comprehensive Documentation

Detailed Features and Benefits

Bilingual understanding (TR/EN): Reduces back-and-forth with users
AI-first classification: Requires Gemini key; ensures consistent, accurate categorization
Human-in-the-loop: Assign experts for high/critical cases or when AI can’t resolve

Installation Guide (Step-by-Step)

Install dependencies with uv sync
Run Django migrations and import experts (see Quick Start)
Launch MCP, Django API, and the Web UI
Test with the usage examples below

Practical Usage Examples

Inside Fast Agent:

/tools
/call main-add_issue {"employee_id":"E001","description":"VPN bağlantı sorunu","category":"network","subcategory":"vpn","priority":"medium"}
/call main-ai_try_solve {"description":"VPN bağlantı sorunu","category":"network","subcategory":"vpn","priority":"medium"}
/call main-process_issues

⚙️ Advanced Configuration

Gemini model: Set GEMINI_MODEL env (default: gemini-1.5-flash)
API Keys (required): Provide GEMINI_API_KEY or GOOGLE_API_KEY. The app maps GEMINI_API_KEY to GOOGLE_API_KEY automatically.
CORS: settings.py allows http://localhost:5001 for the web UI; adjust for production
Secrets & DB: .gitignore excludes local DBs and secrets; use .env files locally (don’t commit)

🧠 Design Philosophy

LLM-first: Classification and validation are fully AI-driven
Single Source of Truth for Experts: Experts live in Django DB (no runtime JSON fallback)

🧪 Testing Ideas

Unit test serializers and classification (LLM prompts and outputs)
Integration test Django actions that shell into MCP (assign_expert, ai_solve)
E2E test via Web UI: create issue → assign expert → verify DB state

🐳 Docker

Official Image

Pull and run:

docker pull minasenel/mcp-it-helpdesk:latest
docker run --rm --name mcp_api -p 8000:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  minasenel/mcp-it-helpdesk:latest
# open http://localhost:8000/api/health/

If port 8000 is busy on your host, map another host port:

docker run --rm --name mcp_api -p 8001:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  minasenel/mcp-it-helpdesk:latest
# then use http://localhost:8001

Notes:

API routes live under /api/. The root / returns 404 by design.
The frontend typically runs at http://localhost:5001 and talks to the API at http://localhost:8000.

Environment Variables

GEMINI_API_KEY or GOOGLE_API_KEY (required)
SECRET_KEY (recommended for production; generated if missing in dev)
DJANGO_ALLOWED_HOSTS (set domains for production)

Examples:

docker run --rm -p 8000:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  -e DJANGO_ALLOWED_HOSTS="localhost,127.0.0.1" \
  -e SECRET_KEY="change-me" \
  minasenel/mcp-it-helpdesk:latest

Data Persistence

The image uses SQLite by default inside the container. Data will be ephemeral unless you mount a volume:

# Persist the Django project folder (including db.sqlite3)
docker run --rm -p 8000:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  -v "$PWD/django_data":/app/django_api_service \
  minasenel/mcp-it-helpdesk:latest

Build locally (optional)

If you prefer to build from source:

# from repo root
docker build -t YOUR_USERNAME/mcp-it-helpdesk:latest .
docker run --rm -p 8000:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  YOUR_USERNAME/mcp-it-helpdesk:latest

Licensed under MIT.

This server cannot be installed

license - not found

quality - not tested

maintenance

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/minasenel/mcp-it-helpdesk'

If you have feedback or need assistance with the MCP directory API, please join our Discord server