MCP IT Help Desk
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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
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
Related MCP server: Freshservice MCP server
π§ 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 |
| Create a new ticket with normalized fields and timestamps |
|
|
| Attempt auto-resolution for common issues (non-critical) |
| Solution text or suggestion to assign expert |
| Classify description and pick best available expert |
|
|
| Batch normalize + auto-solve + assign/queue | none | Summary: closed_by_ai, assigned/queued, skipped |
π©βπ» Expert Data Format (Django DB)
Field | Type | Example | Notes |
| string (pk) |
| Human-friendly ID |
| string |
| Display name |
| JSON/list |
| Tags matched by classifier |
| string |
| Optional |
| boolean |
| Considered for assignment |
| integer |
| Incremented on assignment |
π Quick Start
Prerequisites
Python 3.11+
uv (recommended)
Gemini API key (required): set
GEMINI_API_KEYorGOOGLE_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 8000Terminal 2 β start Web UI (Flask + Socket.IO):
cd .. # back to project root (mcp-it-helpdesk)
uv run python start_web_agent.pySet 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 DBRun 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:5001Notes:
API routes live under
/api/(e.g.,/api/health/,/api/issues/). The root/returns 404 by design.The web frontend at
http://localhost:5001calls the API athttp://localhost:8000by 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 syncRun 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_MODELenv (default:gemini-1.5-flash)API Keys (required): Provide
GEMINI_API_KEYorGOOGLE_API_KEY. The app mapsGEMINI_API_KEYtoGOOGLE_API_KEYautomatically.CORS:
settings.pyallowshttp://localhost:5001for the web UI; adjust for productionSecrets & DB:
.gitignoreexcludes local DBs and secrets; use.envfiles 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:8001Notes:
API routes live under
/api/. The root/returns 404 by design.The frontend typically runs at
http://localhost:5001and talks to the API athttp://localhost:8000.
Environment Variables
GEMINI_API_KEYorGOOGLE_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:latestData 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:latestBuild 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:latestLicensed under MIT.
Available Tools
4 toolsadd_issueD
Inputs: category (required), priority (required), description (required), employee_id (required), +1 more. Returns: result
ai_try_solveC
This tool is used to try to solve the issue with AI first @param description: The description of the issue @param category: The category of the issue @param subcategory: The subcategory of the issue @param priority: The priority of the issue @return: The solution for the issue if it is solved, otherwise "ΓΓΆzΓΌm ΓΆnerisi bulunamadΔ±: uzman atamasΔ± ΓΆnerilir."
Inputs: category (required), priority (required), description (required), subcategory (required). Returns: result
assign_expertC
Analyze the problem description, classify into standard categories, and choose the most suitable available expert.
Inputs: description (required). Returns: result
process_issuesC
This tool is used to process the issues @return: The summary of the issues
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 4 tools
Tools appear distinct but 'add_issue' lacks description, causing ambiguity about its exact role relative to 'ai_try_solve' and 'assign_expert'.
Most tools use verb_noun pattern, but 'ai_try_solve' deviates with an awkward structure mixing AI and action verb.
Four tools are reasonable for a simple help desk server, covering core steps without being excessive.
Missing essential operations like listing, updating, or deleting issues, and lacks a tool for viewing a single issue's details.
Maintenance
Related MCP Connectors
AI-native ITSM and ESM platform. resolve IT and HR requests inside Slack and Teams.
AI support employee for any website: learns the site, answers visitors by chat and voice.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- AlicenseAqualityDmaintenanceThis server provides a comprehensive integration with Zendesk. Retrieving and managing tickets and comments. Ticket analyzes and response drafting. Access to help center articles as knowledge base.7126Apache 2.0
- AlicenseBqualityDmaintenanceMCP server created for Freshservice, allowing AI models to interact with Freshservice modules5939MIT
- AlicenseNot gradedqualityDmaintenanceIntegration server that connects AI assistants to Atlassian products (Confluence & Jira), enabling natural language interactions for searching content, managing issues, creating documents, and updating project information.MIT
- FlicenseNot gradedqualityDmaintenanceAn AI-powered code consultation server that routes programming queries to specific AI models based on requested expertise levels. It enables users to receive structured feedback on debugging, architectural decisions, and code reviews from Gemini, Claude, or GPT.-