claude-skills-vault

Monday.com Workspace Manager

Manage Monday.com workspaces through the official MCP server — create items, update statuses, move tasks between groups, archive/delete items, manage boards & columns, and add comments.

When to Use

Invoke when:

• Creating, updating, or deleting items/tasks on Monday.com
• Managing boards, groups, or columns
• Moving items between groups or boards
• Adding comments/updates to items
• Querying board structure, items, or users
• Setting up Monday.com MCP integration
• Any Monday.com workspace automation

Prerequisites & Setup

First-Time Setup Flow

On first use, check if Monday.com MCP is configured. If not, guide the user through setup using AskUserQuestion:

Question: "How would you like to connect to Monday.com?"
Options:
  - "Hosted MCP (Recommended)" — No local install, auto-updates, OAuth auth
  - "Local MCP via npx" — Requires Node.js 20+, API token
  - "Direct API (curl/scripts)" — Manual GraphQL calls, no MCP dependency

Option A: Hosted MCP (Recommended)

Add to Claude Code MCP settings (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "monday-mcp": {
      "url": "https://mcp.monday.com/mcp"
    }
  }
}

OAuth handles auth automatically — no API token needed.

Option B: Local MCP via npx

1. Get API Token: Monday.com → Avatar → Developers → My access tokens
2. Configure MCP in Claude Code settings:

{
  "mcpServers": {
    "monday-api-mcp": {
      "command": "npx",
      "args": ["@mondaydotcomorg/monday-api-mcp@latest"],
      "env": {
        "MONDAY_TOKEN": "<your_token>"
      }
    }
  }
}

Useful flags:

| Flag | Values | Purpose | |------|--------|---------| | --read-only / -ro | true | Read-only mode | | --enable-dynamic-api-tools / -edat | true / only | Full GraphQL access (beta) | | --version / -v | 2025-07 | API version |

Option C: Direct API (No MCP)

For environments w/o MCP support. Set MONDAY_API_TOKEN in .env or .env.local at project root:

MONDAY_API_TOKEN=your_token_here

The script auto-loads from .env.local (priority) or .env. Alternatively, export the env var directly.

Use scripts/monday_api.sh for direct GraphQL calls.

Tool Selection: MCP vs API Script

On every Monday.com request, determine which tool to use:

1. Check: Are Monday.com MCP tools available? (ToolSearch "monday")
   → YES: Use MCP tools — go to decision table below
   → NO:  Go to step 2

2. Check: Does .env or .env.local have MONDAY_API_TOKEN?
   → YES: Use scripts/monday_api.sh with GraphQL queries
   → NO:  Ask user to set up (AskUserQuestion with setup options above)

MCP vs API Decision Table

| Operation | Best Tool | Why | |-----------|-----------|-----| | Single item CRUD (create, update, delete) | MCP | One tool call, handles auth, structured params | | Get board schema/info | MCP (get_board_info) | Returns columns, groups, filtering guidelines in one call | | Get items w/ filters | MCP (get_board_items_page) | Built-in filtering, ordering, pagination, includeColumns toggle | | Search items by text | MCP (get_board_items_page w/ searchTerm) | Fuzzy search built-in | | Assign owner | MCP (change_item_column_values) | Single call w/ personsAndTeams JSON | | List users/teams | MCP (list_users_and_teams) | Supports getMe, name search, team members | | Create board/group/column | MCP | Type-safe params, enum validation | | Get column type info | MCP (get_column_type_info) | Returns JSON schema for column settings | | Board activity logs | MCP (get_board_activity) | Date range filtering built-in | | Move board/folder | MCP (move_object) | Handles positioning | | Workspace management | MCP | Create, update, list workspaces | | Forms | MCP | Create and get forms | | Multi-board dashboard | API script | MCP queries one board at a time; script queries all boards in one GraphQL call | | Batch updates (5+ items) | API script | One GraphQL mutation w/ aliases vs 5+ separate MCP calls | | Batch deletes | API script | Same — aliases batch multiple deletes into one call | | Webhooks | API script | MCP has no webhook tools | | Archive item/board | API script | MCP has no archive mutation | | Duplicate item | MCP (create_item w/ duplicateFromItemId) | Built-in duplicate support | | Subitems | MCP (create_item w/ parentItemId) | Native subitem creation |

Performance Rules

1. Single operations → always MCP (faster, no shell overhead, structured errors)
2. Bulk operations (5+ items) → API script w/ aliases (1 HTTP call vs N MCP calls)
3. Cross-board reads → API script (query multiple boards in one request)
4. Filtered reads → MCP (built-in filter operators: any_of, between, contains_text, greater_than, etc.)
5. MCP unavailable → API script for everything

Safety Classification

| Tier | Operations | Behavior | |------|-----------|----------| | Safe | List boards, get items, get schema, list users | Execute immediately | | Write | Create item, update columns, add comment, create group/column | Inform user → execute | | Destructive | Delete item, delete column, archive board | AskUserQuestion → confirm → execute |

Decision Flow

Request received
  → Classify tier (see table above)
  → Safe?        Execute immediately, show results
  → Write?       Show what will change → execute
  → Destructive? AskUserQuestion w/ confirm/cancel → execute or abort

Destructive Operation Confirmation

For delete/archive operations, always confirm:

Question: "Delete item 'Task Name' (ID: 123456) from board 'Project Board'?"
Options:
  - "Delete permanently" — Item cannot be recovered
  - "Cancel" — Keep item unchanged

Available MCP Tools

Item Operations

| Tool | Tier | Description | |------|------|-------------| | create_item | Write | Create item w/ column values | | change_item_column_values | Write | Update item columns | | move_item_to_group | Write | Move item between groups | | delete_item | Destructive | Permanently delete item | | get_board_items_by_name | Safe | Search items by name | | create_update | Write | Add comment to item |

Board Operations

| Tool | Tier | Description | |------|------|-------------| | create_board | Write | Create new board | | get_board_schema | Safe | Get columns, groups, structure | | create_group | Write | Add group to board | | create_column | Write | Add column to board | | delete_column | Destructive | Remove column from board |

Account Operations

| Tool | Tier | Description | |------|------|-------------| | list_users_and_teams | Safe | Get workspace users & teams |

Dynamic API Tools (Beta)

Enable w/ --enable-dynamic-api-tools true for full GraphQL access:

| Tool | Description | |------|-------------| | all_monday_api | Execute any GraphQL query/mutation | | get_graphql_schema | Explore API schema | | get_type_details | View type information |

Common Workflows

CRITICAL: Always Discover Board Schema First

Column IDs are unique per board (e.g. status vs project_status, person vs project_owner). Never assume column IDs — always query the board schema first.

Step 0 (always): Get board schema to discover column IDs, group IDs, and user IDs
  → query: { boards(ids: [BOARD_ID]) { columns { id title type } groups { id title } } }
  → query: { users { id name email } }

Create Item w/ Owner & Status

1. Get board schema → find column IDs for people, status, date, etc.
2. Get user ID → query { users { id name } } or { me { id } }
3. Create item using discovered column IDs:

``