monday-com

name: monday-com description: "Monday.com workspace management via official MCP server. This skill should be used when creating, updating, moving, archiving, or deleting items/boards/groups on Monday.com, managing columns, adding comments, or querying workspace data. Supports both hosted and local MCP deployment with interactive setup guidance."

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:

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

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

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

Board Operations

Account Operations

Dynamic API Tools (Beta)

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

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:

mutation {
  create_item(
    board_id: BOARD_ID,
    group_id: "GROUP_ID",
    item_name: "Task name",
    column_values: "{\"PEOPLE_COL_ID\": {\"personsAndTeams\": [{\"id\": USER_ID, \"kind\": \"person\"}]}, \"STATUS_COL_ID\": \"Working on it\"}"
  ) { id name }
}

Assign Owner to Existing Items

1. Get board schema → find the people column ID (type: "people")
2. Get user ID → { users { id name } }
3. Update:

mutation {
  change_multiple_column_values(
    board_id: BOARD_ID,
    item_id: ITEM_ID,
    column_values: "{\"PEOPLE_COL_ID\": {\"personsAndTeams\": [{\"id\": USER_ID, \"kind\": \"person\"}]}}"
  ) { id }
}

Update Item Status

1. Get board schema → find the status column ID (type: "status")
2. Find item → get_board_items_by_name or query items
3. Update:

mutation {
  change_simple_column_value(
    board_id: BOARD_ID,
    item_id: ITEM_ID,
    column_id: "STATUS_COL_ID",
    value: "Done"
  ) { id }
}

Move Item to Different Group

1. get_board_schema → get target group ID
2. move_item_to_group → item_id, group_id

Batch Operations (Multiple Items)

Use GraphQL aliases to batch mutations in a single request:

mutation {
  t1: change_multiple_column_values(board_id: BID, item_id: ID1, column_values: "...") { id }
  t2: change_multiple_column_values(board_id: BID, item_id: ID2, column_values: "...") { id }
  t3: change_multiple_column_values(board_id: BID, item_id: ID3, column_values: "...") { id }
}

Rate limit: 10,000,000 complexity points/min per account.

Column Value Formats

Column IDs vary per board. Always query schema first to find the correct ID.

For complete column type reference, see references/column-types.md.

Advanced Workflows

Workspace Dashboard

To build a dashboard, fetch all boards w/ items in a single query, then parse:

1. Query all boards w/ items_page and column_values
2. Filter out "Subitems of *" boards (auto-generated)
3. Group items by board, status, and owner
4. Present as markdown tables w/ summary stats

Understanding Fields

Column IDs are unique per board and must be discovered via schema query. Key patterns:

• Status and Priority share the same status type — distinguish by title
• People column holds user assignments — always use personsAndTeams JSON format
• text field on column_values = human-readable value; value field = raw JSON
• Status labels (Done, Working on it, Stuck) come from settings_str in column schema

Cross-Board Operations

When moving items between boards, column IDs differ. Use columns_mapping in move_item_to_board to map source → target column IDs.

For complete examples, see references/advanced-workflows.md.

Error Handling

When credentials are missing:

MISSING: MONDAY_TOKEN
ASK_USER: Please provide your Monday.com API token.
LOCATION: Monday.com → Avatar (bottom-left) → Developers → My access tokens

Direct API Fallback

If MCP is unavailable, use scripts/monday_api.sh for direct GraphQL calls:

bash .claude/skills/monday-com/scripts/monday_api.sh query '{ boards(limit:5) { id name } }'

bash .claude/skills/monday-com/scripts/monday_api.sh mutation \
  'mutation { create_item(board_id: 123, item_name: "New Task") { id } }'

References

Integration

Pairs with:

• system-architect — Board/workspace structure design
• brainstorm — Feature planning before task creation