# monday-mcp

A lightweight, independent [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for interacting with the monday.com GraphQL API from MCP-compatible AI assistants and development tools. It exposes a focused set of explicit, validated tools and sends fixed GraphQL operations to monday.com; clients cannot inject arbitrary GraphQL.

## What is monday-mcp?

`monday-mcp` is a lightweight Python MCP server that provides a focused set of tools for common monday.com workflows. It is built around:

- A standard MCP interface over `stdio`.
- Predefined GraphQL operations for users, teams, workspaces, boards, groups, columns, items, and updates.
- Explicit `confirmWrite: true` confirmation for every data-changing tool.
- Straightforward local configuration through the `MONDAY_API_TOKEN` environment variable.

It is an independent open-source project and is not affiliated with, endorsed by, sponsored by, or maintained by monday.com Ltd.

## Features

- Identify the authenticated user and search users and teams.
- List workspaces and boards; inspect a board's groups and columns.
- List board items with cursor pagination; retrieve an item and its updates.
- Create items, rename them, update their column values, and move them between groups.
- Post updates and replies.
- Require `confirmWrite: true` for every data-changing tool.
- Keep the API token in the MCP client's environment, not in command-line arguments.
- Use standard `stdio` MCP transport.

## Architecture

```mermaid
flowchart TD
  A["MCP client or AI assistant"] --> B["monday-mcp (stdio)"]
  B --> C["monday.com GraphQL API"]
  C --> D["monday.com workspace"]
```

## Quick start

```bash
git clone https://github.com/<your-account>/monday-mcp.git
cd monday-mcp
uv sync
```

Create a monday.com personal API token with access to the boards and users you need. Then add this server to an MCP client configuration:

```json
{
  "mcpServers": {
    "monday-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/monday-mcp",
        "monday-mcp"
      ],
      "env": {
        "MONDAY_API_TOKEN": "replace_with_your_monday_api_token"
      }
    }
  }
}
```

Restart or reload the MCP client, then ask it to list your boards, inspect a board, create an item, update its status, or move it to another group. See [installation](docs/installation.md) for a complete setup and [examples](docs/examples.md) for prompts.

## Configuration

`MONDAY_API_TOKEN` is required. Set it in your MCP client's `env` configuration; do not commit a real token or pass one on the command line. See [configuration](docs/configuration.md).

## Documentation

- [Installation](docs/installation.md)
- [Configuration](docs/configuration.md)
- [Capabilities](docs/capabilities.md)
- [Architecture](docs/architecture.md)
- [Examples](docs/examples.md)
- [Troubleshooting](docs/troubleshooting.md)
- [FAQ](docs/faq.md)

## Security

The server reads the token only from `MONDAY_API_TOKEN` at startup and sends it only as the authorization header for requests to `https://api.monday.com/v2`. Every tool that creates or modifies data requires `confirmWrite: true`; grant the token only the access it needs. See [SECURITY.md](SECURITY.md).

## Roadmap

Version 1.0.0 supports essential workspace, board, item, user/team, and update workflows. It intentionally does not expose arbitrary GraphQL, board administration, file upload, OAuth, webhooks, or account administration.

## Contributing

Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

## Disclaimer

This is an independent open-source project and is not affiliated with,
endorsed by, sponsored by, or maintained by monday.com Ltd.

monday.com is a trademark of monday.com Ltd.

## License

This project is licensed under the [MIT License](LICENSE).