monday-for-agents（周一针对 Agent 商）

monday.com for Agents

One skill for everything monday.com: account setup, daily operations, GraphQL API, MCP server, and troubleshooting.

Minimum Model

Any model for routine operations. Use a medium model for debugging GraphQL errors.

Section 1 — Setup

Option A: Manual Account Creation

Each PA needs its own account — do not use the owner's.

1. Go to monday.com/agents-signup.
2. Use the agent email (e.g. agent@agentdomain.com).
3. Owner invites the PA via Admin → Users → Invite.

Get an API Token

1. Log into monday.com as the agent.
2. Click avatar → Developers → My Access Tokens → Copy.
3. Set the token as an environment variable via OpenClaw's config (preferred) or your system's secret manager.

❌ Do not write the token to a plaintext file or add it to shell startup files. ❌ Do not commit tokens to version control.

Recommended: OpenClaw env config Add MONDAY_API_TOKEN to your OpenClaw agent environment via the Ocana dashboard or openclaw.json env block — never hardcode it in scripts.

For local dev only (not production):

export MONDAY_API_TOKEN="TOKEN_HERE"  # current shell only, not persisted

Setup Checklist

[ ] PA has a monday.com account (agent email, not owner's)
[ ] MONDAY_API_TOKEN set in OpenClaw agent environment (not a plaintext file)
[ ] Workspace access confirmed
[ ] Verified with: monday_query '{"query": "{ me { id name } }"}'
[ ] If using MCP: server added to config and tested

Section 2 — Operations

API Basics

Monday.com uses a single GraphQL endpoint:

https://api.monday.com/v2    (preferred)
https://api.monday.com/graphql  (also works)

Reusable Helper

MONDAY_API_URL="https://api.monday.com/v2"

# MONDAY_API_TOKEN must be set in the agent's environment (not read from file)
if [ -z "$MONDAY_API_TOKEN" ]; then
  echo "ERROR: MONDAY_API_TOKEN is not set. Configure it in your OpenClaw agent environment." >&2
  exit 1
fi

monday_query() {
  RESPONSE=$(curl -s -X POST "$MONDAY_API_URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: $MONDAY_API_TOKEN" \
    -H "API-Version: 2024-10" \
    -d "$1")

  if echo "$RESPONSE" | python3 -c "
import sys, json
d = json.load(sys.stdin)
if d.get('errors'):
    print('API ERROR:', d['errors'])
    sys.exit(1)
" 2>/dev/null; then
    echo "$RESPONSE"
  else
    echo "API ERROR: $RESPONSE" >&2
    return 1
  fi
}

Common Operations

# List boards
monday_query '{"query": "{ boards(limit: 25) { id name description state } }"}'

# Get items from a board
monday_query '{"query": "{ boards(ids: [BOARD_ID]) { items_page(limit: 50) { cursor items { id name group { id title } column_values { id title text type } } } } }"}'

# Create an item
monday_query '{
  "query": "mutation ($board: ID!, $name: String!) { create_item(board_id: $board, item_name: $name) { id } }",
  "variables": {"board": "BOARD_ID", "name": "New Task"}
}'

# Update a status column
monday_query '{
  "query": "mutation ($board: ID!, $item: ID!, $col: String!, $val: JSON!) { change_column_value(board_id: $board, item_id: $item, column_id: $col, value: $val) { id } }",
  "variables": {
    "board": "BOARD_ID",
    "item": "ITEM_ID",
    "col": "status",
    "val": "{\"label\": \"Done\"}"
  }
}'

# Add a comment to an item
monday_query '{
  "query": "mutation ($item: ID!, $body: String!) { create_update(item_id: $item, body: $body) { id } }",
  "variables": {"item": "ITEM_ID", "body": "Update text here"}
}'

# List columns in a board
monday_query '{"query": "{ boards(ids: [BOARD_ID]) { columns { id title type } } }"}'

# Query subitems
monday_query '{"query": "{ items(ids: [ITEM_ID]) { subitems { id name column_values { id text } } } }"}'

# Get current user
monday_query '{"query": "{ me { id name email account { id name } } }"}'

Pagination for Large Boards

# First page — also returns a cursor
monday_query '{"query": "{ boards(ids: [BOARD_ID]) { items_page(limit: 100) { cursor items { id name } } } }"}'

# Next page — pass the cursor value from the previous response
monday_query '{"query": "{ next_items_page(limit: 100, cursor: \"CURSOR_VALUE\") { cursor items { id name } } }"}'

Check Before Creating (Avoid Duplicates)

RESULT=$(monday_query '{"query": "{ items_by_multiple_column_values(board_id: BOARD_ID, column_id: \"name\", column_values: [\"Item Name\"]) { id name } }"}')

COUNT=$(echo "$RESULT" | python3 -c "
import sys, json
d = json.load(sys.stdin)
print(len(d.get('data', {}).get('items_by_multiple_column_values', [])))
")

if [ "$COUNT" -eq 0 ]; then
  echo "Item not found — creating"
else
  echo "Item already exists — skipping"
fi

Batch Update Multiple Items

for ITEM_ID in 123456 789012 345678; do
  monday_query "{
    \"query\": \"mutation { change_column_value(board_id: BOARD_ID, item_id: $ITEM_ID, column_id: \\\"status\\\", value: \\\"{\\\\\\\"label\\\\\\\": \\\\\\\"In Progress\\\\\\\"}\\\") { id } }\"
  }"
  sleep 0.2  # Respect rate limits
done

Rate Limits

Monday.com uses complexity-based rate limiting (not simple request counting). Response headers include x-ratelimit-remaining-complexity. Keep queries focused, use pagination, and add sleep 0.2 between batch calls.

Section 3 — MCP Server (Recommended for Daily Use)

The MCP server lets you work with boards using natural language tools — no manual GraphQL needed.

Option A: Hosted MCP

Add to ~/.openclaw/openclaw.json under mcpServers:

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

No local install needed. Uses OAuth.

Test: mcporter call monday-mcp list_boards

Option B: Local MCP (npx)

{
  "mcpServers": {
    "monday-api-mcp": {
      "command": "npx",
      "args": ["@mondaydotcomorg/monday-api-mcp@latest"],
      "env": {
        "MONDAY_API_TOKEN": "your_token_here"
      }
    }
  }
}

Speed tip: npm install -g @mondaydotcomorg/monday-api-mcp then use "command": "monday-api-mcp".

Section 4 — Troubleshooting

Core Operating Rules

Follow these rules every time, without exception:

1. Create → API. Operate → MCP.

- New workspace / board / column: use API (curl + GraphQL) - Daily read/update/create items: use MCP (mcporter)

1. Never guess IDs.

- Before any mutation: run mcporter call monday.list_workspaces or get_board_info first - Store all IDs in TOOLS.md immediately after creation

1. One workspace per context.

- Family ≠ Work ≠ PA Network - Never mix contexts in the same workspace

1. Before any mutation: verify.

- Run mcporter call monday.get_board_info boardId=X to confirm column IDs - Wrong column ID = silent failure or data corruption

1. IDs in TOOLS.md, not memory.

- After creating any resource: echo "board-name: $ID" >> TOOLS.md - Before using an ID: grep "board-name" TOOLS.md

1. Do NOT create or update board items without explicit instruction from owner.

- Always confirm board ID before mutations - Never print or log the API token

Cost Tips

• Cheap: MCP handles natural language → API translation. Prefer it over raw GraphQL.
• Expensive: Fetching all items from large boards without pagination. Always use limit:.
• Small model OK: Routine ops (list, create, update) work with any model.
• Use medium model for: Debugging GraphQL errors or constructing complex queries.

References

• Column value JSON formats: see references/column-types.md in this skill directory
• Full GraphQL cookbook: see references/graphql-operations.md in this skill directory
• monday.com GraphQL API: https://developer.monday.com/api-reference
• MCP server docs: https://mcp.monday.com