@omniq/mcp-server

MCP (Model Context Protocol) server that exposes the OMNIQ project management + CRM platform to AI agents — Cursor, Claude Desktop, Windsurf, and other MCP-compatible clients.

Manage projects, issues, sprints, wiki, calendar, CRM contacts, deals, organizations, pipelines, escalations, and company settings through natural language without leaving your IDE.

Setup

Variant 1 — npm (recommended)

{
  "mcpServers": {
    "omniq": {
      "command": "npx",
      "args": ["-y", "@omniq/mcp-server"],
      "env": {
        "OMNIQ_API_URL": "https://your-instance.omniq.pro/api/v1",
        "OMNIQ_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Variant 2 — Monorepo development

{
  "mcpServers": {
    "omniq": {
      "command": "npx",
      "args": ["tsx", "packages/mcp-server/src/index.ts"],
      "env": {
        "OMNIQ_API_URL": "http://localhost:3000/api/v1",
        "OMNIQ_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Place config in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OMNIQ_API_URL | Yes | http://localhost:3000/api/v1 | OMNIQ API base URL | | OMNIQ_TOKEN | Yes | — | Personal Access Token (Settings → Security → Full access) | | OMNIQ_MCP_CONFIRM | No | false | When true, destructive operations require two-step confirmation |

Tools Reference

Company (9 tools)

Manage the current company — settings, members, branding. Most operations require company_admin role.

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_get_company | Get company info (name, plan, mode, timezone, usage counts) | — | — | | omniq_update_company | Update company settings | — | name, timezone, locale, color, domain | | omniq_list_company_members | List all company members with roles and statuses | — | — | | omniq_add_company_member | Invite new member (creates account, sends email) | email, name, role | locale, projectIds | | omniq_update_company_member | Update member role, status, name, or email | id | name, email, role, status | | omniq_remove_company_member | Remove member from company (soft delete) | id | — | | omniq_reset_member_password | Reset member password and get temp password | id | — | | omniq_get_company_branding | Get branding (logo, colors, domain, email sender) | — | — | | omniq_update_company_branding | Update branding settings | — | brandName, logoUrl, faviconUrl, primaryColor, secondaryColor, customDomain, emailFromName |

Roles for omniq_add_company_member:

• PM roles: project_manager, developer, viewer
• CRM roles: sales_director, sales_manager, sales_agent, support_agent

Typical flow:

1. omniq_get_company              → see company mode (crm/pm/all) and limits
2. omniq_list_company_members     → see who's in the team
3. omniq_add_company_member       → invite a new person

Projects (6 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_projects | List all accessible projects | — | — | | omniq_get_project | Get project details by ID | id | — | | omniq_create_project | Create a new project | name, key | description, color | | omniq_update_project | Update a project | id | name, description, color | | omniq_delete_project | Delete a project permanently | id | — | | omniq_list_project_members | List project members and roles | projectId | — |

Typical flow:

1. omniq_list_projects            → discover project IDs and keys
2. omniq_get_project              → get details for a specific project
3. omniq_list_project_members     → find assignee IDs for issues

Issues (12 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_issues | List issues with filters | projectId | status, assigneeId, search, page, limit | | omniq_get_issue | Get full issue details | id | — | | omniq_create_issue | Create an issue | projectId, title | description, type, priority, assigneeId, storyPoints, labels, sprintId, dueDate, parentId | | omniq_create_epic | Create an epic | projectId, title | description, priority, assigneeId, labels | | omniq_update_issue | Update issue fields | id | title, description, status, priority, type, assigneeId, storyPoints, sprintId, labels, dueDate, parentId | | omniq_change_status | Change issue status | id, status | — | | omniq_assign_issue | Assign or unassign issue | id, assigneeId | — | | omniq_get_my_issues | Get issues assigned to me | projectId | status | | omniq_delete_issue | Delete an issue | id | — | | omniq_bulk_update_issues | Bulk-update multiple issues | ids | status, assigneeId, sprintId | | omniq_add_comment | Add comment to an issue | issueId, content | — | | omniq_link_issues | Link two issues | issueId, targetId, relation | — |

Key conventions:

• Issue keys: PROJECT_KEY-NUMBER (e.g. CRM-42)
• Story points: Fibonacci only — 1, 2, 3, 5, 8, 13, 21, 34
• Statuses: backlog → in_progress → review → testing → done
• Types: epic, feature, task, bug, subtask
• Priorities: critical, high, medium, low
• Use "me" as assigneeId to assign to current user

Sprints (9 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_sprints | List sprints for a project | projectId | — | | omniq_get_sprint | Get sprint details + burndown | id | — | | omniq_create_sprint | Create a planned sprint | projectId, name | goal, startDate, endDate | | omniq_start_sprint | Activate a planned sprint | id | — | | omniq_close_sprint | Close the active sprint | id | transferToSprintId | | omniq_delete_sprint | Delete a sprint | id | — | | omniq_add_to_sprint | Add an issue to a sprint | issueId, sprintId | — | | omniq_get_burndown | Get burndown chart data | sprintId | — | | omniq_get_velocity | Get velocity across sprints | projectId | — |

Typical flow:

1. omniq_create_sprint            → create a new sprint
2. omniq_add_to_sprint            → add issues to the sprint
3. omniq_start_sprint             → activate when ready
4. omniq_get_burndown             → track progress
5. omniq_close_sprint             → complete (optionally transfer remaining issues)

CRM — Contacts (7 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_contacts | List contacts with filters | — | search, organizationId, tag, source, page, limit | | omniq_get_contact | Get contact details with orgs and deals | id | — | | omniq_create_contact | Create a contact | email | name, phone, jobTitle, source, tags | | omniq_update_contact | Update contact fields | id | email, name, phone, jobTitle, source, tags | | omniq_delete_contact | Delete a contact | id | — | | omniq_link_contact_org | Link contact to organization | contactId, organizationId | role, isPrimary | | omniq_unlink_contact_org | Remove contact-organization link | contactId, organizationId | — |

Contact-organization roles: decision_maker, influencer, user, billing, technical

CRM — Organizations (5 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_organizations | List organizations | — | search, industry, tag, page, limit | | omniq_get_organization | Get organization details | id | — | | omniq_create_organization | Create an organization | name | email, phone, website, industry, size, address, fiscalCode, vatNumber, tags | | omniq_update_organization | Update organization fields | id | name, email, phone, website, industry, size, address, fiscalCode, vatNumber, tags | | omniq_delete_organization | Delete an organization | id | — |

CRM — Pipelines (8 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_crm_pipelines | List all sales pipelines with stages | — | — | | omniq_get_crm_pipeline | Get pipeline details with all stages | id | — | | omniq_create_crm_pipeline | Create pipeline with stages (min 2) | name, stages[] | isDefault, color | | omniq_update_crm_pipeline | Update pipeline name/color/default | id | name, isDefault, color | | omniq_delete_crm_pipeline | Delete an empty pipeline | id | — | | omniq_add_crm_pipeline_stage | Add a stage to existing pipeline | pipelineId, name | probability, color, position, isWon, isLost, rottenDays | | omniq_update_crm_pipeline_stage | Update stage properties | pipelineId, stageId | name, probability, color, rottenDays, isWon, isLost | | omniq_reorder_crm_pipeline_stages | Reorder stages in a pipeline | pipelineId, stageIds[] | — |

Stage fields:

• probability — win probability (0–100%). E.g. Lead=10, Qualified=25, Proposal=50, Won=100
• rottenDays — days before deal is flagged as "rotten" if stuck in this stage
• isWon / isLost — mark terminal stages (exactly one of each per pipeline)
• color — hex color (e.g. #6366f1)

Typical pipeline creation:

omniq_create_crm_pipeline({
  name: "Investimento Clienti",
  stages: [
    { name: "Lead",         probability: 10 },
    { name: "Qualificato",  probability: 25, rottenDays: 14 },
    { name: "Proposta",     probability: 50, rottenDays: 7 },
    { name: "Negoziazione", probability: 75, rottenDays: 5 },
    { name: "Vinto",        probability: 100, isWon: true },
    { name: "Perso",        probability: 0,   isLost: true }
  ]
})

CRM — Deals (6 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_deals | List deals with filters | — | pipelineId, stageId, assigneeId, contactId, organizationId, status, page, limit | | omniq_get_deal | Get deal details with contact, org, stage | id | — | | omniq_create_deal | Create a deal | title, pipelineId, stageId | amount, currency, contactId, organizationId, assigneeId, tags, expectedCloseDate | | omniq_update_deal | Update deal fields | id | title, amount, currency, contactId, organizationId, assigneeId, tags, expectedCloseDate | | omniq_delete_deal | Delete a deal | id | — | | omniq_move_deal_stage | Move deal to a different stage | id, stageId | — |

Deal statuses: open, won, lost

Typical CRM flow:

1. omniq_list_crm_pipelines       → find pipeline and stage IDs
2. omniq_create_contact            → create the person
3. omniq_create_organization       → create their company
4. omniq_link_contact_org          → link person to company (role: decision_maker)
5. omniq_create_deal               → create deal linked to contact + org
6. omniq_move_deal_stage           → progress deal through pipeline
7. omniq_create_activity           → log calls, meetings, notes

CRM — Activities (2 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_activities | List CRM activities (timeline) | — | contactId, dealId, page, limit | | omniq_create_activity | Log an activity | type | description, contactId, dealId, organizationId, duration, scheduledAt |

Activity types: call, email, meeting, note, task, sms, whatsapp

CRM — Escalations (4 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_escalations | List escalations | — | status, priority, assigneeId, page, limit | | omniq_create_escalation | Create an escalation | title, reason | priority, dealId, description, assigneeId, slaDeadline | | omniq_assign_escalation | Assign escalation to a user | id, assigneeId | — | | omniq_resolve_escalation | Mark escalation as resolved | id | — |

Escalation reasons: sla_breach, customer_request, ai_unable, manual, deal_rotten Priorities: critical, high, medium, low

Wiki (6 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_wiki_spaces | List wiki spaces in a project | projectId | — | | omniq_create_wiki_space | Create a wiki space | projectId, name | slug | | omniq_list_wiki_pages | List pages in a space | spaceId | — | | omniq_create_wiki_page | Create a wiki page | spaceId, title, content | parentId | | omniq_update_wiki_page | Update a wiki page | id | title, content | | omniq_search_wiki | Full-text search in wiki | projectId, query | — |

Calendar (6 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_events | List events in a date range | start, end | projectId, userId | | omniq_create_event | Create a calendar event | title, type, start | end, allDay, description, projectId, color | | omniq_create_meeting | Create a meeting (shortcut) | title, start | end, description, projectId, attendeeIds, videoUrl | | omniq_my_schedule | Get my schedule for today | — | start, end | | omniq_update_event | Update a calendar event | id | title, start, end, description, type, allDay, color | | omniq_delete_event | Delete a calendar event | id | — |

Event types: meeting, deadline, sprint, release, task

AI (3 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_ai_chat | Chat with OMNIQ AI assistant | message | projectId, conversationId | | omniq_ai_generate_description | Generate issue description from title | title | projectId | | omniq_ai_estimate | Estimate story points with AI | title, description | — |

GitLab (3 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_gitlab_activity | List recent GitLab activity | projectId | — | | omniq_list_pipelines | List GitLab CI/CD pipelines | projectId | — | | omniq_link_commit | Link a commit to an issue | issueId, sha | url |

Portal — Widget Config (2 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_get_portal_widget_config | Get current widget configuration | — | — | | omniq_update_portal_widget_config | Update widget design and behavior | — | primaryColor, greeting, avatarUrl, language, workHoursFrom, workHoursTo, timezone |

Widget config fields:

• primaryColor — brand color in hex (e.g. #4338ca, #d4af37)
• greeting — welcome message shown to visitors
• avatarUrl — logo/avatar for the chat bubble
• language — widget UI language (it, en, ru, etc.)
• workHoursFrom / workHoursTo — business hours (e.g. 09:00 – 18:00)
• timezone — timezone for work hours (e.g. Europe/Rome)

Portal — Knowledge Base (4 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_portal_knowledge | List all knowledge base articles | — | — | | omniq_create_portal_knowledge | Create article (AI uses these to answer customers) | title, content | category, tags | | omniq_update_portal_knowledge | Update article | id | title, content, category, tags | | omniq_delete_portal_knowledge | Delete article | id | — |

Typical use: Add product info, pricing, FAQs — the Portal AI assistant uses these to answer customer chat questions.

Portal — Conversations (5 tools)

| Tool | Description | Required params | Optional params | |------|-------------|-----------------|-----------------| | omniq_list_portal_conversations | List chat conversations | — | status (open_conv, resolved, escalated) | | omniq_get_portal_conversation_messages | Get messages in a conversation | conversationId | — | | omniq_portal_takeover_conversation | Take over from AI as human agent | conversationId | — | | omniq_portal_reply | Send agent reply | conversationId, content | — | | omniq_portal_resolve_conversation | Close/resolve a conversation | conversationId | rating (1–5) |

Typical flow:

1. omniq_list_portal_conversations status=open_conv  → see active chats
2. omniq_get_portal_conversation_messages             → read chat history
3. omniq_portal_takeover_conversation                 → take over from AI
4. omniq_portal_reply                                 → respond to customer
5. omniq_portal_resolve_conversation                  → close when done

System (1 tool)

| Tool | Description | Required params | |------|-------------|-----------------| | omniq_confirm_action | Confirm a pending destructive action | confirmationId |

Resources

MCP Resources provide read-only data that clients can subscribe to:

| URI | Description | |-----|-------------| | omniq://projects | All accessible projects | | omniq://projects/{projectId}/issues | Active issues (in_progress) for a project | | omniq://me/schedule | Today's calendar events for current user | | omniq://sprints/current/{projectId} | Current sprint + burndown data |

Confirmation Flow

When OMNIQ_MCP_CONFIRM=true, destructive operations follow a two-step process:

1. Request a destructive action (e.g., omniq_delete_deal)
2. Server returns a confirmationId (expires in 60 seconds)
3. Call omniq_confirm_action with that confirmationId to proceed

Affected tools: omniq_delete_project, omniq_delete_issue, omniq_delete_event, omniq_delete_sprint, omniq_delete_contact, omniq_delete_organization, omniq_delete_deal, omniq_delete_crm_pipeline, omniq_delete_portal_knowledge, omniq_remove_company_member

Example Prompts

Project Management

| Prompt | Tools used | |--------|-----------| | "Show all projects" | omniq_list_projects | | "Create task in CRM: Refactor auth" | omniq_create_issue | | "What's on my plate today?" | omniq_my_schedule + omniq_get_my_issues | | "Estimate this task in story points" | omniq_ai_estimate | | "What issues are in review?" | omniq_list_issues with status=review | | "Move CRM-12, CRM-14 to sprint 5" | omniq_bulk_update_issues | | "Create a meeting tomorrow at 3pm" | omniq_create_meeting | | "Start the current sprint" | omniq_list_sprints → omniq_start_sprint |

CRM

| Prompt | Tools used | |--------|-----------| | "List all contacts" | omniq_list_contacts | | "Create contact [email protected]" | omniq_create_contact | | "Create organization Acme Corp" | omniq_create_organization | | "Link John to Acme as decision maker" | omniq_link_contact_org | | "Show me the sales pipeline" | omniq_list_crm_pipelines | | "Create pipeline Investimento Clienti with 6 stages" | omniq_create_crm_pipeline | | "Add a Discovery stage to pipeline X" | omniq_add_crm_pipeline_stage | | "Create a deal for Acme, €50k" | omniq_create_deal | | "Move deal to Negotiation stage" | omniq_move_deal_stage | | "Log a call with John, 15 min" | omniq_create_activity | | "Show deals assigned to me" | omniq_list_deals with assigneeId=me | | "Create escalation: SLA breach on deal X" | omniq_create_escalation |

Company Management

| Prompt | Tools used | |--------|-----------| | "Show company info" | omniq_get_company | | "Who's in the team?" | omniq_list_company_members | | "Add developer [email protected]" | omniq_add_company_member | | "Change Maria's role to sales_manager" | omniq_update_company_member | | "Reset John's password" | omniq_reset_member_password | | "Update company timezone to Europe/Rome" | omniq_update_company |

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | Red MCP indicator in Cursor | Server failed to start | Check OMNIQ_TOKEN is set and valid | | "Cannot authenticate" on startup | Wrong API URL or expired token | Verify OMNIQ_API_URL; regenerate token in Settings → Security | | 403 Forbidden errors | Insufficient role or scopes | Use token with Full access preset | | "Confirmation not found or expired" | Took >60s to confirm | Retry the original action | | Tool returns empty results | Wrong project/pipeline ID | Run omniq_list_projects or omniq_list_crm_pipelines first | | CRM tools return 403 | User role can't access CRM | Need sales_*, support_agent, company_admin, or project_manager role |

Development

pnpm dev          # Run with tsx (watch mode)
pnpm typecheck    # Type-check
pnpm build        # Build for production
pnpm test         # Run tests