monday-graphql-mcp

Un servidor MCP que ayuda a los desarrolladores a crear aplicaciones sobre la API GraphQL de monday.com: validación de consultas, formatos de valores de columna, explicación de errores, introspección de esquema en vivo y generación de código de andamiaje, todo desde tu asistente de IA.

Herramientas

Related MCP server: Monday.com MCP Server

Configuración

1. Instalar y compilar

git clone <repo-url> monday-graphql-mcp
cd monday-graphql-mcp
npm install
npm run build

2. Añadir a Claude Code

Añade esto a tu ~/.claude/settings.json dentro de mcpServers:

{
  "mcpServers": {
    "monday-graphql-mcp": {
      "command": "node",
      "args": ["/path/to/monday-graphql-mcp/dist/index.js"],
      "env": {
        "MONDAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Obtén tu clave de API: monday.com → Avatar → Administración → API.

Reinicia Claude Code después de actualizar la configuración.

3. Usar sin clave

column_value_format, explain_error y scaffold funcionan inmediatamente sin necesidad de clave de API.

Ejemplos de uso

Obtener el formato exacto de un tipo de columna

How do I write a people column value?
→ uses column_value_format({ column_type: "people" })

{
  "personsAndTeams": [{ "id": 12345678, "kind": "person" }]
}

Decodificar un error de la API

I'm getting "ColumnValueException: invalid value" — what's wrong?
→ uses explain_error({ error: "...", query: "..." })

Validar una consulta antes de ejecutarla

query {
  boards(ids: [123]) {
    items_page(limit: 500) {
      items {
        id
        name
        column_values { id text value }
        subitems { id name }
      }
    }
  }
}

→ validate_query flags:
  - Estimated complexity: ~4200 (HIGH — likely to hit limits)
  - limit: 500 is the hard cap, but combined with subitems + all column_values this is expensive
  - Fetching all column_values without ids filter — add ids: ["col1"] to reduce complexity
  - Fetching subitems + column_values together — consider two separate queries

Generar código de plantilla

Scaffold a TypeScript webhook listener for monday.com
→ uses scaffold({ type: "webhook-listener", language: "typescript" })

Tipos de scaffold: api-client, webhook-listener, oauth-flow, integration, board-view, dashboard-widget
Lenguajes: typescript, javascript, python

Obtener el esquema en vivo

Show me the monday.com schema for item-related types
→ uses get_schema({ filter: "item" })

Ejecutar una consulta

query {
  me {
    id
    name
    email
  }
}

→ uses run_query({ query: "..." })

Tipos de columna compatibles

text · long_text · numbers · status · people · date · timeline · checkbox · dropdown · link · email · phone · rating · country · board_relation · dependency · tags · hour · week · world_clock · color_picker · location · formula · mirror · auto_number · creation_log · last_updated · item_id · vote · files · subtasks

Desarrollo

npm run dev      # run with tsx (no build step)
npm run build    # compile TypeScript to dist/
npm start        # run compiled output

El servidor se comunica a través de stdin/stdout usando el protocolo MCP — está diseñado para que lo lance un host MCP (Claude Code, Claude Desktop, etc.), no para ejecutarse directamente en una terminal.