monday-mcp

A local Model Context Protocol server for monday.com.

It runs on your machine and speaks straight to the monday.com GraphQL API. Your token stays on your machine. No relay, no hosted middle layer, no telemetry.

Unofficial. This project is not built by monday.com, and it carries no endorsement from monday.com. "monday.com" is a trademark of monday.com Ltd.

Claude, Cursor, or any MCP client
        |  stdio
   monday-mcp  (this server, on your machine)
        |  HTTPS
   api.monday.com

Why another monday.com server

Most failures with the monday.com API come from one thing: every column type stores a different JSON shape. A model that writes "Done" into a status column gets a silent no-op or an error with no clue in it.

This server does the translation. You send a plain value, and the server converts it to the shape monday.com stores.

// what the model sends
{ "Status": "Done", "Due date": "2026-08-14", "Owner": [12345678] }

// what monday.com receives
{
  "status":  { "index": 1 },
  "date_1":  { "date": "2026-08-14" },
  "person":  { "personsAndTeams": [{ "id": 12345678, "kind": "person" }] }
}

The server also refuses a bad value before it sends a request, and the refusal names the labels the column accepts:

Column "Status" has no status "Shipped".
It accepts: "Working on it", "Done", "Stuck".
Send create_labels_if_missing true to add it.

Three more things this server does:

• Column titles work as keys. Use "Due date" or date_1. Letter case, spaces, hyphens and underscores do not matter.

• Status filters translate too. A filter on "Stuck" becomes the numeric label index that the API needs.

• Safety rails. A read-only mode, a board allow list, and a permanent delete that needs explicit confirmation.

Related MCP server: JSON Canvas MCP Server

Install

Node 20 or newer.

git clone https://github.com/ashrocket/monday-mcp.git
cd monday-mcp
npm install          # this also builds, through the prepare script

Get an API token

1. Open monday.com.

2. Click your avatar at the bottom left.

3. Choose Developers, then My access tokens, then Show.

4. Copy the token.

An admin may prefer the account token at Administration > API.

The token carries your own permissions. It sees the boards you see.

Connect it

Claude Code

claude mcp add monday --env MONDAY_API_TOKEN=your-token -- node /full/path/to/monday-mcp/dist/index.js

Claude Desktop, Cursor, and other clients

Add this to the MCP server configuration file:

{
  "mcpServers": {
    "monday": {
      "command": "node",
      "args": ["/full/path/to/monday-mcp/dist/index.js"],
      "env": { "MONDAY_API_TOKEN": "your-token" }
    }
  }
}

To keep the token out of the configuration file, put it in a file and point at the file instead:

{
  "mcpServers": {
    "monday": {
      "command": "node",
      "args": [
        "/full/path/to/monday-mcp/dist/index.js",
        "--token-file",
        "~/.config/monday/token"
      ]
    }
  }
}

The server takes its configuration from the environment that the MCP client gives it. It does not read a .env file by itself. For local work, use Node's own flag: node --env-file=.env dist/index.js.

Prove it works

cp .env.example .env      # then put your token in .env
npm run smoke             # read-only checks against your account
npm run smoke -- --write  # adds a create, update, comment and archive cycle

The write cycle archives the item that it makes, so it leaves no clutter.

Tools

A read-only server registers the nine read tools only. monday_graphql stays, but it refuses a mutation.

Column values

Pass values keyed by column id or column title. Use the plain form below. An object value passes through untouched, so you keep control when you need the exact API shape.

Send null to clear a column.

Three notes on the awkward ones:

• phone needs a country as well as a number. An international number carries one, so "+442071234567" works. A local number does not, so send ["07700900123", "GB"].

• location stores coordinates. monday.com does not turn an address into coordinates, and neither does this server, so send lat and lng.

• status and dropdown reject a label the board does not have. Pass create_labels_if_missing: true to add it instead.

These types are not writable, because monday.com computes them: auto_number, button, creation_log, formula, integration, item_id, last_updated, mirror, progress, subtasks, time_tracking, vote.

A file or doc column needs the separate upload endpoint, which this server does not expose.

Safety

The token never appears in a tool result or an error message. The client redacts it before anything leaves the process.

Options

A flag always wins over the matching environment variable.

About the API version

monday.com retires an API version every quarter, and a request that names a retired version quietly gets the maintenance version instead. That makes a stale default worse than no default, so this server pins a current one and you can override it. Check the versioning page when you upgrade.

Rate limits

monday.com meters a complexity budget, not a request count. The client reads the reset hint from the throttle response, whether it arrives in the retry-after header or in the message body, and waits for that long. Other transient failures use exponential backoff.

Retrying stops after about 45 seconds in total. A complexity window can be a full minute, and waiting three of them outlasts every MCP client, so the server reports the throttle and lets the caller decide to try again.

Board layouts stay in a cache for one minute, which keeps a run of writes off the budget.

Develop

npm test          # 115 tests, no network
npm run typecheck # source and tests
npm run build
npm run dev       # rebuild on save

The tests run the real MCP server against a fake monday.com API over an in-memory transport. They assert the exact JSON that goes over the wire. test/regressions.test.ts holds one test per defect found so far, named after the behaviour that was wrong.

Contributing

See CONTRIBUTING.md. To report a security problem, see SECURITY.md.

Licence

MIT. See LICENSE.