@omniq/mcp-server

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

Manage projects, issues, sprints, wiki pages, calendar events, and more through natural language without leaving your IDE.

Setup

Variant 1 — Monorepo development (recommended for contributors)

Run from the repository root using tsx:

{
  "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 this in .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global).

Variant 2 — Built package

After running pnpm build in the monorepo:

{
  "mcpServers": {
    "omniq": {
      "command": "node",
      "args": ["packages/mcp-server/dist/index.js"],
      "env": {
        "OMNIQ_API_URL": "https://your-instance.omniq.pro/api/v1",
        "OMNIQ_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Variant 3 — npm (future)

Once published to the registry:

{
  "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"
      }
    }
  }
}

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 (create in Settings → Security with Full access preset) | | OMNIQ_MCP_CONFIRM | No | false | When true, destructive operations (delete) require a two-step confirmation |

Tools

Projects

| 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 | — |

Issues

| 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 | — |

Sprints

| 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 | — |

Wiki

| 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

| 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 | — |

AI

| 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

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

System

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

Resources

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

| URI | Description | Data returned | |-----|-------------|---------------| | omniq://projects | All accessible projects | Array of projects with id, name, key, color | | omniq://projects/{projectId}/issues | Active issues for a project | Issues with status in_progress | | omniq://me/schedule | Today's calendar events | Events for the current user today | | omniq://sprints/current/{projectId} | Current sprint + burndown | Active sprint details with daily burndown data |

Confirmation Flow

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

1. You request a destructive action (e.g., omniq_delete_project)
2. Instead of executing immediately, the server returns a confirmationId with a 60-second expiry
3. To proceed, call omniq_confirm_action with that confirmationId
4. If the confirmation expires, you must retry the original action

Affected tools: omniq_delete_project, omniq_delete_issue, omniq_delete_event, omniq_delete_sprint

This prevents accidental data loss when AI agents misinterpret a request.

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | Red MCP indicator in Cursor status bar | Server failed to start or authenticate | Check that OMNIQ_TOKEN is set and valid | | "Cannot authenticate" on startup | Wrong API URL or invalid/expired token | Verify OMNIQ_API_URL points to a running instance; regenerate token | | 403 Forbidden errors | Token lacks required scopes or role | Ensure the token was created with Full access preset, or with all necessary scopes selected in Custom mode (projects, issues, sprints, wiki, calendar, ai, git) | | "Confirmation not found or expired" | Took longer than 60s to confirm | Retry the original destructive action and confirm faster | | Tool returns empty results | Wrong project ID or no data | Run omniq_list_projects first to discover valid project IDs |

Example Prompts

| What you say | Tool invoked | Notes | |--------------|-------------|-------| | "Покажи все проекты" | omniq_list_projects | Discovers all accessible projects | | "Создай задачу в CRM: Рефакторинг авторизации" | omniq_create_issue | Uses project key to resolve project ID | | "Что у меня сегодня?" | omniq_my_schedule | Returns today's events for current user | | "Оцени задачу в story points" | omniq_ai_estimate | AI analyzes title+description, returns Fibonacci estimate | | "Какие задачи в review?" | omniq_list_issues | Filters with status=review | | "Перенеси задачи CRM-12, CRM-14 в спринт 5" | omniq_bulk_update_issues | Bulk-moves issues to a sprint | | "Создай встречу завтра в 15:00 на час" | omniq_create_meeting | Creates meeting with start/end times |

Development

# Run in development mode (watch)
pnpm dev

# Type-check
pnpm typecheck

# Build for production
pnpm build