# monday-graphql-mcp

An MCP server that helps developers build on the monday.com GraphQL API — query validation, column value formats, error explanations, live schema introspection, and code scaffolding, all from your AI assistant.

## Tools

| Tool | API Key Required | Description |
|---|---|---|
| `column_value_format` | No | Exact read/write JSON format for any column type |
| `explain_error` | No | Decode API errors and get a fix suggestion |
| `scaffold` | No | Boilerplate code for integrations, webhooks, OAuth, and apps |
| `validate_query` | Optional | Syntax check, complexity estimate, and lint warnings |
| `get_schema` | Yes | Live schema introspection, filterable by keyword |
| `run_query` | Yes | Execute a query or mutation against the API |

## Setup

### 1. Install and build

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

### 2. Add to Claude Code

Add this to your `~/.claude/settings.json` under `mcpServers`:

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

Get your API key: **monday.com → Avatar → Administration → API**.

Restart Claude Code after updating the config.

### 3. Use without a key

`column_value_format`, `explain_error`, and `scaffold` work immediately with no API key.

---

## Usage Examples

### Get the exact format for a column type

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

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

### Decode an API error

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

### Validate a query before running it

```graphql
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
```

### Generate boilerplate

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

Scaffold types: `api-client`, `webhook-listener`, `oauth-flow`, `integration`, `board-view`, `dashboard-widget`  
Languages: `typescript`, `javascript`, `python`

### Fetch the live schema

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

### Run a query

```graphql
query {
  me {
    id
    name
    email
  }
}
```

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

---

## Supported Column Types

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

---

## Development

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

The server communicates over stdin/stdout using the MCP protocol — it's designed to be launched by an MCP host (Claude Code, Claude Desktop, etc.), not run directly in a terminal.