VTrack Server

MCP (Model Context Protocol) server that exposes the V-Track project management API as tools for AI assistants.

Setup

1. Install dependencies

npm install

2. Build

npm run build

3. Configure

Set environment variables before starting:

Variable	Description	Default
VTRACK_BASE_URL	V-Track API base URL	http://localhost:3000
VTRACK_ACCESS_TOKEN	Bearer access token	(empty)

Or call the configure tool at runtime to set them dynamically.

4. Run

npm start
# or for development
npm run dev

---

Connecting to Claude Desktop / Claude Code

Add to your MCP config (e.g. ~/.claude/settings.json or Claude Desktop config):

{
  "mcpServers": {
    "vtrack": {
      "command": "node",
      "args": ["D:/workspace/vtrack-mcp/dist/index.js"],
      "env": {
        "VTRACK_BASE_URL": "https://your-vtrack-api.example.com",
        "VTRACK_ACCESS_TOKEN": "your-bearer-token"
      }
    }
  }
}

---

Available Tools

Meta

Tool	Description
configure	Set base URL and access token at runtime

Auth

Tool	Description
auth_login	Login, returns accessToken + refreshToken
auth_refresh	Refresh access token
auth_logout	Logout current user

Users

Tool	Description
users_list	Paginated user list
users_me	Current user info
users_detail	User detail by ID

Projects

Tool	Description
projects_list	Paginated project list
projects_detail	Project detail by ID
projects_export_members_excel	Export members as Excel

Tasks

Tool	Description
tasks_list	Paginated task list with filters
tasks_detail	Task detail by ID
tasks_kanban_board	Kanban board grouped by status

Backlog

Tool	Description
backlog_list	Paginated backlog (feature tasks)
backlog_detail	Backlog item detail

Issues

Tool	Description
issues_list	Paginated issues (bug tasks)
issues_detail	Issue detail by ID

Sprints

Tool	Description
sprints_list	Paginated sprint list
sprints_list_active	Active sprints only
sprints_detail	Sprint detail by ID
sprints_list_for_filter	Lightweight sprint list for dropdowns

Project Members

Tool	Description
project_members_list	Members of a project

Task Comments

Tool	Description
task_comments_list	Comments for a task (cursor-based)
task_comments_detail	Comment detail by ID

Attachments

Tool	Description
attachments_list	Attachments for an entity
attachments_detail	Attachment detail by ID

Requests

Tool	Description
requests_list	Paginated request list
requests_detail	Request detail by ID

Milestones

Tool	Description
milestones_list	Paginated milestone list
milestones_detail	Milestone detail by ID

Reports

Tool	Description
reports_global	System-wide metrics
reports_attention	System-wide alerts
reports_project	Project-level report
reports_export_data	Exportable project data
reports_project_attention	Project-level alerts

Workload

Tool	Description
workload_list	Workload per team member

Lookup Tables

Tool	Description
lookup_priorities	All priorities
lookup_roles	All system roles
lookup_project_roles	All project roles
lookup_task_types	Task types (optionally by project)
lookup_request_types	Request types (optionally by project)
lookup_request_channels	Request channels
lookup_statuses	All statuses (no auth required)

Notifications

Tool	Description
notifications_list	User's notifications
notifications_mark_read	Mark one notification as read
notifications_mark_all_read	Mark all notifications as read

Meeting Notes

Tool	Description
meeting_notes_list	Paginated meeting notes
meeting_notes_detail	Meeting note detail by ID

Service Monitors

Tool	Description
service_monitors_list	Paginated monitor list
service_monitors_detail	Monitor detail
service_monitors_logs	Monitor logs
service_monitors_incidents	Incident list
service_monitors_incident_detail	Incident detail
service_monitors_sla_stats	SLA statistics
service_monitors_uptime_stats	Uptime statistics

Misc

Tool	Description
health_check	API health check
audit_logs	Paginated audit logs

---

Response Format

All V-Track responses follow this envelope:

{
  "code": 0,
  "message": "...",
  "data": {},
  "total": 100,
  "totalPages": 10
}

code: 0 = success. Errors: -2 bad request, -3 unauthorized, -4 not found.