mcp-miro

This MCP server provides a bridge between AI assistants and Miro boards. It exposes a set of MCP tools that map to common Miro actions, such as listing boards, creating and updating boards, and manipulating items on boards (cards, sticky notes, frames, images, text, and more). With this server configured, you can drive Miro programmatically from your AI assistant or workflow by invoking the mapped MCP tools (for example list-boards, create-board, update-board, get-items-on-board, create-card-item, etc.). The server is designed to be used with Claude Desktop as shown in the readme, but it can be integrated into any MCP-compliant client that can call the provided MCP endpoints.

To use it, install and run the MCP server via npx with the package name, providing your Miro OAuth access token as an environment variable (MIRO_ACCESS_TOKEN). The server exposes a comprehensive toolset for board and item management, including support for connectors, groups, tags, and a wide variety of item types (cards, sticky notes, images, frames, documents, mindmaps, and more). The tooling table in the README confirms which operations are available; you can perform create, read, update, and delete actions across boards, items, and their attributes. Once running, you can issue commands through your MCP client to perform these actions against your Miro workspace.

Prerequisites:

• Node.js v16 or newer installed
• npm (comes with Node.js)
• A Miro account and OAuth access token with the required permissions (as listed in the README)

Installation steps:

1. Clone or install the MCP-Miro package:
   • If using npm/npx directly: npm install -g @k-jarzyna/mcp-miro (or rely on npx to install on demand)
2. Ensure your environment is prepared:
   • Create a token with the required scopes from the Miro Developer Portal (boards:read, boards:write, identity:read, identity:write, team:read, team:write)
3. Set up your environment file (optional but recommended):
   • Create a .env file (or use your environment) with MIRO_ACCESS_TOKEN=your_miro_access_token
4. Test-run or develop locally:
   • Use the Local Development instructions from the README:

npm install

cp .env.template .env

Edit the .env file to add your Miro access token.

npm run build

node build/index.js

Note: The README shows running via npx with the package name; you can rely on the mcp-miro package entry point by using:

npx -y @k-jarzyna/mcp-miro

Tips and common issues:

• Ensure MIRO_ACCESS_TOKEN is set and has sufficient scopes as listed (readonly and writable permissions).
• If Claude Desktop integration is used, ensure the config.json points to the npx command and environment variable as shown in the README snippet.
• When running locally, remember to build before starting the server: npm run build followed by node build/index.js.
• If you encounter token expiration, refresh the token in the Miro Developer Portal and update the MIRO_ACCESS_TOKEN value.
• The server exposes a wide range of MCP tools for board and item operations; refer to the Available Tools and Resources table in the README to see supported actions.
• If deploying behind a proxy or in restricted environments, ensure network access to Miro APIs and that environment variables are properly propagated to the running process.