How do I use MCP IT Help Desk?

1. Click on "Deploy 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 Source Related Servers Discussions Admin

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

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
`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.

Available Tools

4 tools

add_issueD

ParametersJSON Schema

Name	Required	Description	Default
`category`	Yes
`priority`	Yes
`description`	Yes
`employee_id`	Yes
`subcategory`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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."

ParametersJSON Schema

Name	Required	Description	Default
`category`	Yes
`priority`	Yes
`description`	Yes
`subcategory`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full burden. It discloses the return value (solution or fallback message) but does not mention side effects (e.g., does it modify data?), required permissions, or what happens on failure beyond the message. The behavioral impact is unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence plus @param lines. The @param lines add little value and could be removed. It is not excessively long, but the Javadoc-style formatting is slightly verbose for the content provided.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and an output schema present, the description covers the return value but lacks detail on parameter formats or edge cases. With 4 required params, more guidance would improve completeness. The fallback message provides useful context for when the tool fails.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. The @param comments only repeat parameter names (e.g., 'The description of the issue') without adding meaning, allowed values, or format. With no enums or further details, the semantics are weak.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool's purpose: 'try to solve the issue with AI first'. It clearly identifies the verb-resource pair (try solve issue) and distinguishes from siblings like assign_expert which assigns experts. However, it does not explicitly differentiate from add_issue or process_issues.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a workflow by stating 'try to solve with AI first' and the return message suggests assigning an expert if no solution is found. However, it lacks explicit guidance on when to use this tool versus alternatives, such as prerequisites or cases where it should not be used.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

assign_expertC

Analyze the problem description, classify into standard categories, and choose the most suitable available expert.

ParametersJSON Schema

Name	Required	Description	Default
`description`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It describes analysis and selection but does not disclose whether the tool performs an actual assignment (side effect) or is read-only. No information about required permissions, data persistence, or side effects is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is straightforward and free of unnecessary words. It could benefit from a more structured format (e.g., bullet points) but is not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core functionality but lacks usage context and behavioral details. Given an output schema exists, return values are likely documented elsewhere, but the absence of when-to-use guidance and side-effect disclosure leaves gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The sole parameter 'description' has 0% schema description, so the tool description's mention of 'problem description' clarifies its purpose. However, no additional constraints like expected length, format, or examples are given, meaning the description adds minimal value beyond the parameter name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes a problem description, classifies it into categories, and chooses an expert. This gives a specific verb-resource pairing. However, it does not explicitly differentiate from sibling tools like 'add_issue' or 'ai_try_solve', missing context on how assignment differs from issue creation or AI solving.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, scenarios where this tool is appropriate, or cases where another sibling tool should be used instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

process_issuesC

This tool is used to process the issues @return: The summary of the issues

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It does not disclose whether processing is destructive, requires permissions, or any side effects. The only hint is 'summary of the issues', suggesting it may be a read operation, but 'process' implies mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (two sentences) but lacks substance. While concise, it is under-specified and does not effectively communicate the tool's purpose or behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and a vague description, the tool is incomplete for an agent. The output schema exists but is not shown; the description only mentions a summary. More context about what 'process' does is needed, especially without annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100% (vacuously). Baseline 3 applies. The description adds no param info because none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description says 'process the issues' but does not specify what processing entails. It is vague and does not distinguish from sibling tools like add_issue, ai_try_solve, and assign_expert.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.1.0Jul 30, 2026
- First observedadd_issue
- First observedai_try_solve
- First observedassign_expert
- First observedprocess_issues

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.1/5.0

Scored 2026-07-30 06:25 across 4 tools

Disambiguation3/5

Tools appear distinct but 'add_issue' lacks description, causing ambiguity about its exact role relative to 'ai_try_solve' and 'assign_expert'.

Naming Consistency3/5

Most tools use verb_noun pattern, but 'ai_try_solve' deviates with an awkward structure mixing AI and action verb.

Tool Count4/5

Four tools are reasonable for a simple help desk server, covering core steps without being excessive.

Completeness2/5

Missing essential operations like listing, updating, or deleting issues, and lacks a tool for viewing a single issue's details.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Corebee AI Customer SupportOAuth
io.github.jonny-1812
Run AI customer support from your terminal: conversations, knowledge base, and chat widget.
Customer Support Communication
2
Artificial Wit AIOAuth
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
mcpOAuth
com.gibsonai
GibsonAI MCP server: manage your databases with natural language
Databases Search
233
inbrixOAuth
ai.inbrix
AI-native helpdesk hosted in Germany: tickets, replies, KPIs and knowledge base over MCP.
Customer Support
1

Related MCP Servers

zendesk-mcp-server
Customer Support Knowledge & Memory
reminia
A
license
A
quality
B
maintenance
This 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.
Updated 19 days ago (2026-08-27 18:12 UTC)
7
119
Apache 2.0
Freshservice MCP server
Customer Support Autonomous Agents
effytech
A
license
B
quality
D
maintenance
MCP server created for Freshservice, allowing AI models to interact with Freshservice modules
Updated 5 months ago (2026-04-10 05:32 UTC)
59
36
MIT
MCP Atlassian
thienntdev
A
license
Not graded
quality
D
maintenance
Integration 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.
Updated a year ago (2025-07-09 02:52 UTC)
MIT
Dev Guru
Developer Tools Code Analysis Coding Agents
chameleonbr
F
license
Not graded
quality
D
maintenance
An 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.
Updated 6 months ago (2026-03-12 06:28 UTC)
-