Miro MCP Server

Model Context Protocol (MCP) server for Miro API with OAuth2 authentication. Enables Claude AI to programmatically create and manipulate Miro boards.

Features

• Full OAuth2 Support: Authorization code flow with automatic token refresh
• 14 MCP Tools covering all essential Miro operations:
  • Board operations (list, get, create)
  • Item operations (list, get, update, delete)
  • Item creation (sticky notes, shapes, text, frames)
  • Connectors (create, update)
• Rate Limiting: Built-in handling of Miro's API rate limits
• Error Handling: Comprehensive error reporting and recovery

Architecture Pattern

Standalone Single-Account MCP Server:

This server follows the standalone pattern where it manages its own Miro OAuth tokens:

• One server instance = one Miro account (the server owner's account)
• Tokens stored locally (/data/tokens.json in production, ~/.config/mcps/miro-dev/tokens.json in development)
• No multi-user support (all clients use the same Miro account)
• Reauthentication URL: ${BASE_URI}/oauth/authorize (the server itself)

Comparison with mcp-gateway pattern:

This is different from the mcp-gateway architecture where:

• The gateway manages tokens per user across multiple services
• Each user has their own service accounts (Gmail, Miro, etc.)
• Tokens stored in gateway database
• Reauthentication URL: ${GATEWAY_URL}/mcp/miro/oauth/authorize?user_id=X

Choose standalone when:

• ✅ Single Miro account for all Claude users
• ✅ Simpler deployment (no gateway infrastructure)
• ✅ Direct MCP connection

Choose gateway when:

• ✅ Multiple users with different Miro accounts
• ✅ Unified access control across services
• ✅ Centralized token management

Installation

npm install
npm run build

Configuration

1. Set up environment variables

Copy .env.example to .env and configure:

cp .env.example .env

Edit .env:

MIRO_CLIENT_ID=your_client_id
MIRO_CLIENT_SECRET=your_client_secret
MIRO_REDIRECT_URI=http://localhost:3000/oauth/callback

2. Get OAuth2 tokens

The provided tokens have expired. You need to obtain new tokens:

Option A: Manual OAuth2 Flow

1. Visit the authorization URL:

https://miro.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/oauth/callback

2. Authorize the app and copy the code from the redirect URL

3. Exchange the code for tokens:

curl -X POST "https://api.miro.com/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=YOUR_CODE_HERE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=http://localhost:3000/oauth/callback"

4. Copy the access_token and refresh_token to your .env file

Option B: Use Existing OAuth Helper (TODO)

A simple OAuth callback server will be added to automate this process.

Usage

Test API Access

npm test

This will:

• Verify authentication
• List your boards
• Create a test board
• Create items on the test board

Start MCP Server

npm run dev    # Development mode with auto-reload
npm start      # Production mode

Configure in Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "miro-dev": {
      "command": "node",
      "args": ["/path/to/miro-mcp/dist/index.js"],
      "env": {
        "MIRO_CLIENT_ID": "YOUR_CLIENT_ID",
        "MIRO_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "MIRO_ACCESS_TOKEN": "your_access_token",
        "MIRO_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Available Tools

Board Operations

• list_boards - List all accessible boards
• get_board - Get board details
• create_board - Create a new board

Item Operations

• list_items - List items with optional type filtering
• get_item - Get item details
• update_item - Update item properties
• delete_item - Delete an item

Item Creation

• create_sticky_note - Create sticky notes with custom styling
• create_shape - Create shapes (rectangle, circle, etc.)
• create_text - Create text items
• create_frame - Create frames for grouping

Connectors

• create_connector - Create lines/arrows between items
• update_connector - Update connector styling

Example Usage with Claude

Create a Miro board showing 3 agile squads (Alpha, Beta, Gamma).
Each squad has 1 Product Owner, 1 Scrum Master, and 5 developers.
Use frames for each squad, sticky notes for team members, and connectors
to show reporting lines.

Color coding:
- Product Owners: yellow sticky notes
- Scrum Masters: green sticky notes
- Developers: blue sticky notes

Development

Project Structure

miro-mcp/
├── src/
│   ├── index.ts         # MCP server entry point
│   ├── oauth.ts         # OAuth2 manager
│   ├── miro-client.ts   # Miro API client wrapper
│   ├── tools.ts         # MCP tool definitions
│   ├── test-api.ts      # API testing script
│   └── test-mcp.ts      # MCP protocol tests
├── dist/                # Compiled JavaScript
├── package.json
├── tsconfig.json
└── .env                 # Configuration (not in git)

Running Tests

npm run build          # Build TypeScript
npm test              # Test API access
npm run test:integration  # Test MCP protocol

Troubleshooting

Token Expired Error

If you see authentication errors:

1. The access token expires after 1 hour
2. The server will automatically refresh using the refresh token
3. If refresh token also expires, you need to re-authenticate

Automatic Reauthentication Flow:

When tokens are expired or invalid, Claude Desktop/Code will receive an error with a reauthentication URL:

{
  "error": {
    "code": -32001,
    "message": "Miro authentication expired or invalid.",
    "data": {
      "authorize_url": "https://your-server.com/oauth/authorize",
      "action_hint": "Visit the authorize_url to reauthenticate with Miro"
    }
  }
}

To reauthenticate:

1. Visit the authorize_url from the error message
2. You'll be redirected to Miro for authorization
3. After approval, tokens are automatically saved
4. Retry your original request

Rate Limiting

Miro allows 100 requests/minute per user. The client tracks rate limits and will report errors if exceeded.

Connection Issues

Make sure:

• Environment variables are set correctly
• Tokens are valid and not expired
• Network allows access to api.miro.com

API Documentation

• Miro REST API Reference
• Miro OAuth Guide
• MCP Specification

License

MIT