mcp

🌟 Overview

This repository, maintained by the monday.com AI team, provides a comprehensive set of tools for AI agent developers who want to integrate with monday.com. Whether you're building AI assistants, automations, or custom integrations, our tools make it easy to connect to the monday.com platform.

https://github.com/user-attachments/assets/ed8d24e1-256b-4f6b-9d84-38e54a8703fd

🔑 What is monday.com?

monday.com is a work operating system that powers teams to run processes, projects, and everyday work. Teams use monday.com to plan, track, and manage their work in one centralized platform. It provides a visual, intuitive interface where teams can:

• Create and manage projects with customizable boards
• Track tasks through different stages with status columns
• Collaborate with team members through updates and mentions
• Automate workflows and integrate with other tools
• Visualize data with dashboards and reports

📦 What's Inside

💻 monday API MCP Server

The @mondaydotcomorg/monday-api-mcp package provides a plug-and-play server implementation for the Model Context Protocol (MCP). It allows AI agents to interact with the monday.com API without needing to build complex integrations.

🤖 Agent Toolkit

The @mondaydotcomorg/agent-toolkit package provides a powerful set of tools and utilities for building AI agents that interact with the monday.com API, supporting both OpenAI and Model Context Protocol (MCP) implementations.

🏁 Complete Installation Guide

Step 1: Create a monday.com Account

If you don't already have a monday.com account:

1. Go to monday.com and sign up for an account
2. Create your first workspace and board to get started

Step 2: Generate an API Token

To interact with monday.com's API, you'll need an API token:

1. Log in to your monday.com account
2. Click on your avatar in the bottom-left corner
3. Select "Developers"
4. Click "My access tokens" on the left menu
5. Copy your personal access token

Step 3: Configure Your MCP Client

For Claude Desktop

1. Open Claude Desktop
2. Go to Settings → MCP Servers
3. Add a new server with this configuration:

{
  "mcpServers": {
    "monday-api-mcp": {
      "command": "npx",
      "args": [
        "@mondaydotcomorg/monday-api-mcp",
        "-t",
        "your_monday_api_token"
      ]
    }
  }
}

For Cursor or Other MCP Clients

Add to your settings:

{
  "mcpServers": {
    "monday-api-mcp": {
      "command": "npx",
      "args": [
        "@mondaydotcomorg/monday-api-mcp",
        "-t",
        "your_monday_api_token"
      ],
      "env": {}
    }
  }
}

Step 5: Test Your Integration

1. Ask Claude or your AI assistant a question like:

   • "What items do I have in board 123?"
   • "Can you create a board to manage my project?"

2. Your assistant should now be able to interact with your monday.com account!

🌩️ Using the Hosted MCP Service

Option 1: Using OAuth

Instead of running the MCP server locally, you can use monday.com's hosted MCP service for a simpler setup.

Step 1: Install the Monday MCP App

Before using the hosted service, you need to install the Monday MCP app from the marketplace:

1. Visit monday MCP app in the marketplace
2. Click "Install" and follow the instructions to add it to your account

Step 2: Configure Your MCP Client for the Hosted Service

Add this configuration to your MCP client settings:

{
  "mcpServers": {
    "monday-api-mcp-hosted": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.monday.com/sse",
      ],
    }
  }
}

Option 2: Using Authorization header

To specify an authorization header and API version:

{
  "mcpServers": {
    "monday-api-mcp-hosted-dev": {
      "command": "npx",
      "args": [
        "-p",
        "node@20",
        "mcp-remote",
        "https://monday-mcp-server-staging.staging-7c7.workers.dev/sse",
        "--header",
        "Authorization:${AUTH_HEADER}",
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your_token>",
      }
    }
  }
}

Additional Configuration for Hosted MCP

You can specify the Api version you want to use using the --header param:

{
  "mcpServers": {
    "monday-api-mcp-hosted": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.monday.com/sse",
        "--header",
        "Api-Version:${API_VERSION}"
      ],
      "env": {
        "API_VERSION": "2025-07"
      }
    }
  }
}

Benefits of the Hosted Service

• No need to manage your own server
• Automatic updates with the latest features
• Improved reliability and performance
• Instead of adding the token yourself, our OAuth mechanism takes control of it
• You can limit the mcp to work on specific workspaces

🧰 Available Tools

Our MCP server provides a rich set of tools that give AI assistants the ability to interact with monday.com:

🔮 Dynamic API Tools (Beta)

Our Dynamic API Tools feature represents a significant advancement in how AI agents can interact with monday.com. While our standard tools cover common operations, Dynamic API Tools unlock the full potential of the monday.com GraphQL API.

What are Dynamic API Tools?

Dynamic API Tools provide AI agents with complete, adaptable access to monday.com's entire API surface. This means your AI assistant can:

1. Access any API endpoint - Not just the predefined operations we've built
2. Generate custom GraphQL queries - Create exactly the query needed for any situation
3. Dynamically explore monday.com's schema - Understand all available data types and their relationships

Key Dynamic API Tools

Unlocked Possibilities

With Dynamic API Tools, your AI assistants can:

• Create complex reports spanning multiple boards, items, and data points
• Perform batch operations across many items simultaneously
• Integrate deeply with monday.com's advanced features like docs, workspaces, and activity logs
• Discover new capabilities as monday.com adds features to their API

How to Enable

Dynamic API Tools are in beta and disabled by default. Enable them with:

npx @mondaydotcomorg/monday-api-mcp -t your_token --enable-dynamic-api-tools true

You can also use the 'only' mode to exclusively enable Dynamic API Tools:

npx @mondaydotcomorg/monday-api-mcp -t your_token --enable-dynamic-api-tools only

When 'only' mode is enabled, the server will provide just the Dynamic API Tools, filtering out all other standard tools. This is useful for advanced users who want to work directly with the GraphQL API.

⚠️ Note: Dynamic API Tools require full API access and are not compatible with read-only mode.

🖥️ MCP Server Configuration

🔐 Authentication & Security

The server requires a monday.com API token to authenticate with the monday.com API. You can provide this token in two ways:

1. Command line argument: -t your_monday_api_token
2. Environment variable: monday_token=your_monday_api_token

Security Best Practices

• Never share your API token in public repositories or discussions
• Consider using read-only mode (--read-only) when you only need to retrieve data
• Regularly rotate your API tokens for enhanced security

📚 Example Use Cases

Here are some examples of what you can build with our tools:

1. AI Assistant for Project Management

• Create and manage tasks in monday.com boards
• Get updates on project status
• Move items between groups as they progress

2. Data Analysis & Reporting

• Extract data from monday.com boards
• Generate reports and insights
• Create new boards for reporting

3. Automated Workflows

• Create items based on external triggers
• Update item statuses based on conditions
• Link related items across boards

🌐 Community & Support

• GitHub Issues: For bug reports and feature requests
• Discussions: For questions and community discussions
• monday.com Developer Documentation: Learn more about the monday.com API

📚 Documentation

• monday.com API Reference

📋 Prerequisites

Before using these tools, make sure you have:

1. Node.js v20 or higher installed
2. NPM v5.2.0 or higher installed
3. A monday.com API token

🛠️ Working Locally

To work with this repository locally:

1. Clone the repository
2. Install dependencies: yarn install
3. Build the project: yarn build
4. Copy the path of the dist/index.js file in the mcp package.
5. Change the config to work locally

    "monday-api-mcp": {
      "command": "node",
      "args": [
        "<your_full_path_to_the_package>/dist/index.js",
        "-t",
        "123",
        "--enable-dynamic-api-tools",
        "true"
      ],
      "env": {}
    }

🤝 Contributing

We welcome contributions from the community! Whether it's fixing bugs, improving documentation, or adding new features, your help is appreciated.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add some amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

It is clarified that the server uses the monday.com API, which is subject to monday.com's Developer Terms