OskarSch24/mcp-miro-http-server

MCP Miro HTTP Server

HTTP-based Model Context Protocol (MCP) server for Miro API integration with Railway deployment support.

🚀 Features

• HTTP MCP Server - Built on official MCP SDK with Express.js
• Miro API Integration - Access boards, items, and content
• Railway Ready - Optimized for Railway.app deployment
• Health Monitoring - Built-in health check endpoint
• Environment Configurable - Easy setup with environment variables

🛠️ Available Tools

Board Management

• list-boards - List all accessible Miro boards
• get-board-info - Get detailed information about a specific board
• get-board-items - Get all items from a specific board

Testing & Diagnostics

• test-miro-connection - Test the connection to Miro API

📋 Environment Variables

MIRO_ACCESS_TOKEN=your_miro_access_token_here
PANTA_FLOWS_BOARD_ID=uXjVJVMXvuI=  # Optional: specific board ID
PORT=3000
NODE_ENV=production

🚀 Deployment

Railway (Recommended)

1. Deploy to Railway:

2. Set Environment Variables:

   • MIRO_ACCESS_TOKEN - Your Miro API access token
   • PORT - 3000 (automatically set by Railway)
   • NODE_ENV - production

3. Health Check:

   • URL: https://your-app.up.railway.app/health
   • MCP Endpoint: https://your-app.up.railway.app/mcp

Local Development

# Install dependencies
npm install

# Set environment variables
export MIRO_ACCESS_TOKEN=your_token_here
export PANTA_FLOWS_BOARD_ID=your_board_id
export PORT=3000

# Build and start
npm run build
npm start

# Health check
curl http://localhost:3000/health

# Test MCP endpoint
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

🔧 MCP Client Configuration

Cursor

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "miro": {
      "type": "http",
      "url": "https://your-app.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer your_miro_token"
      }
    }
  }
}

Claude Desktop

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "servers": {
    "miro": {
      "type": "http", 
      "url": "https://your-app.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer ${input:miro_access_token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "miro_access_token",
      "description": "Miro Access Token",
      "password": true
    }
  ]
}

🔑 Getting Miro Access Token

1. Go to Miro Developer Portal
2. Create a new app or use existing app
3. Configure permissions:
   • ✅ boards:read - Read board contents
   • ✅ boards:write - Create and modify content
   • ✅ identity:read - User information
4. Generate access token
5. Copy token and use as MIRO_ACCESS_TOKEN

📊 API Endpoints

• Health Check: GET /health
• MCP Protocol: POST /mcp
• SSE Stream: GET /mcp (with session ID)
• Session Termination: DELETE /mcp (with session ID)

🏗️ Architecture

Built on:

• Express.js - HTTP server framework
• MCP SDK - Official Model Context Protocol SDK
• TypeScript - Type safety and modern JavaScript
• Fetch API - Direct Miro API integration

📝 Example Usage

// List all boards
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list-boards"
  }
}

// Get board information
{
  "jsonrpc": "2.0", 
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get-board-info",
    "arguments": {
      "board_id": "uXjVJVMXvuI="
    }
  }
}

// Test connection
{
  "jsonrpc": "2.0",
  "id": 3, 
  "method": "tools/call",
  "params": {
    "name": "test-miro-connection"
  }
}

🐛 Troubleshooting

Server Not Starting

• Check environment variables are set
• Verify Miro access token is valid
• Check port 3000 is available

API Errors

• Verify MIRO_ACCESS_TOKEN is correct
• Check token permissions in Miro Developer Portal
• Ensure board IDs are valid

Railway Deployment Issues

• Check build logs in Railway dashboard
• Verify environment variables are set in Railway
• Check health endpoint after deployment

📄 License

MIT License

🤝 Contributing

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

Live Demo: https://mcp-miro-production.up.railway.app Health Check: https://mcp-miro-production.up.railway.app/health