Motion MCP Server

Motion MCP Server

AI アシスタントが Motion API と連携し、タスクやプロジェクトをインテリジェントに管理できるようにするオープンソースの MCP サーバーです。

目次

• 作成の動機
• 機能
• AI の効率を高めるスマートなデータ取得
• Motion のタスク管理について
• セットアップ
• Claude Desktop での使用
• MCP Proxy 経由で SSE/HTTP クライアントを使用
• AI を Motion に接続するその他の方法
• レート制限
• レート制限エラーについて
• クレジットと謝辞
• トラブルシューティング
• コントリビューション
• ライセンス

作成の動機

この Motion MCP Server を作成した主な動機は、強力な AI アシスタント（Claude Desktop、Cursor など）と、Motion（https://www.usemotion.com/）の堅牢なタスク・プロジェクト管理機能をシームレスに連携させることです。MCP ツールを通じて Motion の API を公開することで、ユーザーは好みの AI アシスタントと自然言語でやり取りしながら、タスク、プロジェクト、スケジュールを管理できます。これにより、対話型 AI と、個人やチームの体系的な生産性との隔たりを埋め、より直感的で効率的なワークフローの実現を目指します。

機能

• Motion API のさまざまなエンドポイント（プロジェクト、タスク、ユーザーなど）に対応する MCP ツール。
• Motion API のクォータ超過を防ぐ自動レート制限（3 分あたり 12 回の呼び出し）。
• ローカルの SQLite データベースを使用し、サーバーの再起動後もレート制限の状態を保持します。

AI の効率を高めるスマートなデータ取得

この MCP サーバーは、特にやり取りするデータの量と関連性を考慮して、AI アシスタント向けに設計されています。API を利用すると、冗長な応答が返され、すぐには役立たない情報で AI のコンテキストウィンドウが埋め尽くされることがよくあります。この問題に対処するため、サーバーにはトークン効率を高めるいくつかの仕組みが組み込まれています。

• 適切なデフォルト設定： タスクやプロジェクトの取得など、データを取得するほとんどのツールでは、厳選されたデフォルトのフィールドが返されます。これらのデフォルト値は、一目で役立つ一般的な情報が得られるように選ばれており、不要な情報に煩わされることなく重要な詳細を確認できます。

• ユーザーが詳細度を指定可能： デフォルト設定が便利な一方で、必要な情報はいつでも指定できます。さらに（または別の）情報が必要な場合は、Motion API から特定のフィールドを取得するよう AI アシスタントに指示できます。追加の詳細をいくつか求めることも、特定の項目の全データを求めることもできます。この柔軟性により、必要なときに必要な情報を正確に取得できます。

• 複雑なデータをインテリジェントに処理： リストや入れ子になった情報など、複雑なデータ構造をスマートに処理します。たとえば、次のような処理を行います。

  • タスクの担当者一覧を尋ねた場合、簡潔さを優先して、デフォルトでは名前だけを返すことがあります。
  • 日付は多くの場合、一貫性のある人間が読みやすい YYYY-MM-DD 形式に自動で変換されます。
  • 入れ子になったオブジェクト内の情報（プロジェクトマネージャーの詳細など）は、直接参照（例：manager.name）したり、デフォルトで簡略化したりできます。

全体としての目標は、Motion のワークスペースから豊富で有益なデータを提供しながら、AI アシスタントの運用上の制約にも配慮し、バランスを取ることです。これにより、やり取りがよりスムーズかつ迅速になり、ワークフローに本当に重要な情報に集中できます。

Motion タスク管理について

Motion（https://www.usemotion.com/）は、タスク管理、プロジェクト計画、カレンダーのスケジュール設定を統合し、自動化するために設計された AI 搭載プラットフォームです。この MCP サーバーに関連する主な機能は次のとおりです。

• AI によるタスクとカレンダーの計画： Motion は、優先度、締め切り、依存関係、利用可能な時間を考慮し、AI を使ってタスクをカレンダーに自動でスケジュールします。新しい項目が発生したり、計画が変更されたりすると、スケジュールを動的に調整します。
• インテリジェントな優先順位付け： このプラットフォームは、最も緊急かつ重要なタスクを特定して優先できるよう支援します。また、リスクのある項目を事前に通知し、締め切りの遅れを防ぐことを目指しています。
• 統合ワークスペース： プロジェクト、タスク、カレンダーを一元化し、多くの場合、メールやメッセージングアプリなどの他のツールとも連携して、作業を一元管理します。

この MCP サーバーを使うと、AI アシスタントはこれらの機能を利用できるようになり、ユーザーは自然言語で Motion のタスクやスケジュールを操作できます。

セットアップ

Motion MCP Server をセットアップして実行するには、次の手順に従ってください。

1. リポジトリをクローンします：

   git clone <your_repository_url_here> # 実際の URL に置き換えてください
   cd motion_mcp_server
   

2. Node.js のバージョン（better-sqlite3 に不可欠）： このプロジェクトでは、ネイティブ Node.js モジュールである better-sqlite3 を使用します。ネイティブモジュールは、NODE_MODULE_VERSION で識別される特定の Node.js アプリケーションバイナリインターフェース（ABI）バージョンに対してコンパイルされます。

   • 問題： あるバージョンの Node.js（例：v21.x、NODE_MODULE_VERSION 120）で依存関係（npm install）をインストールした後、ABI に互換性のない別のバージョンの Node.js（例：Claude Desktop は Node.js v18.x、NODE_MODULE_VERSION 108 を使用することが多い）を使う MCP クライアントでサーバーを実行しようとすると、ERR_DLOPEN_FAILED エラーが発生します。通常、エラーメッセージには、モジュールが「別の Node.js バージョンに対してコンパイルされている」と表示されます。
   • 解決方法：
     • MCP クライアントが使用している Node.js のバージョンを確認します。 たとえば、Claude Desktop のログには、使用中の Node.js バージョン（例：「Node.js v18.19.0」）が表示されることが多いです。Cursor では、2024 年 5 月時点で、Node.js v21.1.0 がこの MCP サーバーで正しく動作することが確認されています。
     • nvm や nvs などの Node.js バージョンマネージャーを使い、次の手順に進む前に、ローカルターミナルで 同じ Node.js バージョン をインストールして切り替えます。

       # Claude Desktop が Node v18.19.0 を使用する場合の nvm の例
       nvm install 18.19.0
       nvm use 18.19.0
       
       # Cursor が対象クライアントで（v21.1.0 を使用する場合）の nvm の例
       nvm install 21.1.0
       nvm use 21.1.0
       

     • クライアントの Node.js バージョンがわからない場合は、幅広い互換性を得るため、通常は Node.js LTS バージョン（例：v18.x、v20.x）が適しています。ただし、この特定のサーバーとクライアントの組み合わせでは、互換性が確認されているバージョンを指定するのが最善です。

3. 依存関係をインストールします： ターミナルで正しい Node.js バージョンが使用されていることを確認してから、依存関係をインストールします。

   npm install
   

   この手順で better-sqlite3 がインストールされ、現在使用中の Node.js バージョンに合わせてコンパイルされます。 重要： その後、別のプロジェクトのためにローカルの Node.js バージョンを切り替えた場合、このプロジェクトを MCP クライアントで再び動作させるには、better-sqlite3 を再ビルドする必要があることがあります。その場合は、npm rebuild better-sqlite3 --update-binary を実行するか、node_modules を削除し、正しい Node.js バージョンを使用している状態で npm install を再度実行してください。

4. API キーを設定する： サーバーは、MOTION_API_KEY という名前の環境変数で Motion API キーを利用できることを想定しています。

   • MCP クライアント（Claude Desktop、Cursor など）の場合： クライアントの MCP サーバー設定でこれを設定します。例については、「Claude Desktop での使用」セクションを参照してください。
   • ローカルシェルで実行する場合（テスト／開発）：

     export MOTION_API_KEY="your_motion_api_key_here"
     

     "your_motion_api_key_here" を実際の Motion API キーに置き換えてください。

5. サーバーを起動する： 通常、MCP クライアントでツールを呼び出すと、サーバーは自動的に起動します。

   • npx tsx を使ったローカル開発／テストの場合（推奨）： サーバーを直接実行する場合（MCP Inspector での使用など）は、プロジェクトのルートディレクトリにいること、および使用中の Node.js のバージョンが npm install で使用したバージョンと一致していることを確認してください。

     npx tsx main.ts
     

     tsx は TypeScript ファイルを直接実行するユーティリティです。初めて使用する場合は、インストールするか、ts-node を使用する必要がある場合があります。
   • npm start を使う場合（設定されている場合）： package.json に "start": "tsx main.ts" のような start スクリプトがある場合は、次のように実行できます。

     npm start
     

   MCP Inspector でのデバッグ

   @modelcontextprotocol/inspector は、MCP サーバーをローカルでテストおよびデバッグするための便利なツールです。クライアント（Inspector の Web UI など）と MCP サーバー間の通信を確認できます。

   1. MCP クライアントの設定ファイルでサーバーが設定されていることを確認する（推奨）： Inspector を使用する最も簡単な方法は、motion サーバーがすでに定義されている既存の MCP クライアント設定ファイルを指定することです（「Claude Desktop での使用」セクションで説明されているとおりです）。たとえば、Claude Desktop の設定を使用する場合は、次のようにします。

      npx @modelcontextprotocol/inspector --config "/path/to/your/Claude/claude_desktop_config.json" --server motion
      

      • "/path/to/your/Claude/claude_desktop_config.json" を、実際の Claude Desktop 設定ファイルのパスに置き換えてください。
      • --server motion フラグは、その設定ファイル内の「motion」という名前のサーバーを Inspector が特にプロキシするよう指定します。

   2. 完全な設定ファイルを使わずに MCP Inspector を使用する場合（代替方法）： 可能ではありますが、コマンド、引数、環境変数など、すべてのサーバーパラメーターをコマンドライン引数で Inspector に直接渡す必要があるため、より複雑です。Claude Desktop などのクライアント用にサーバーをすでに定義している場合は、上記のように --config フラグと --server フラグを使うほうが簡単です。

   3. Inspector にアクセスする： 起動すると、MCP Inspector は URL（通常は http://127.0.0.1:6274）を出力します。この URL を Web ブラウザーで開いてください。そこから「motion」サーバーを選択し、利用可能なツールを確認して、レート制限を含む応答や動作をテストするための呼び出しを実行できます。

   Inspector の使用に関する重要事項：

   • npm install（better-sqlite3 用）を実行するときにターミナルで使用中の Node.js のバージョンが、MCP Inspector によるサーバー起動時に使用されるバージョンと同じであることを確認してください。MCP Inspector が別のシステム Node.js を使用すると、NODE_MODULE_VERSION の不一致が発生する場合があります。Inspector がサーバーの起動に使用するコマンドは、多くの場合、起動ログで確認できます。
   • Inspector がサーバーに渡せるよう、MOTION_API_KEY が claude_desktop_config.json 内のサーバー定義の env セクションに正しく設定されている必要があります。

Claude Desktop での使用方法

この Motion MCP サーバーを Claude Desktop で使用するには、次の手順を実行します。

1. Claude Desktop の設定ファイルを確認します。 通常、次の場所にあります。

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. claude_desktop_config.json ファイルを編集します。 mcpServers セクションに「motion」サーバーのエントリを追加または更新します。 重要：

   • "/path/to/your/motion_mcp_server/main.ts" を、クローンしたリポジトリ内の main.ts ファイルの絶対パスに置き換えます。
   • "YOUR_MOTION_API_KEY_HERE" を実際の Motion API キーに置き換えます。

   {
     "mcpServers": {
       "motion": {
         "command": "npx",
         "args": [
           "tsx",
           "/path/to/your/motion_mcp_server/main.ts"  // <-- IMPORTANT: Change this path
         ],
         "env": {
           "MOTION_API_KEY": "YOUR_MOTION_API_KEY_HERE" // <-- IMPORTANT: Change this key
         }
       }
     }
   }
   

3. Claude Desktop を再起動します。 設定ファイルを保存した後、変更を反映するには Claude Desktop を完全に終了して再起動する必要があります。

設定して再起動すると、Claude から Motion ツール（例：「motion get_tasks」）を呼び出せるようになります。

MCP Proxy 経由での SSE／HTTP クライアントの使用方法

一部の AI クライアントやアプリケーションは、標準の MCP stdio プロトコルではなく、Server-Sent Events（SSE）またはストリーミング可能な HTTP 接続のみをサポートしています。これらのクライアントでは、mcp-proxy サーバーを使用して、HTTP／SSE クライアントとこの Motion MCP サーバー間の接続を中継できます。

前提条件

先に進む前に、次の項目を含む、この Motion MCP サーバーの基本的なセットアップ手順が完了していることを確認してください。

• Node.js と依存関係のインストール
• MOTION_API_KEY の設定

MCP Proxy のインストール

mcp-proxy サーバーはブリッジとして機能し、HTTP／SSE リクエストを、この Motion サーバーとの MCP stdio 通信に変換します。

1. uv を使用して mcp-proxy をインストールします。

   uv tool install git+https://github.com/sparfenyuk/mcp-proxy
   

2. インストールを確認し、バイナリの場所を特定します。 技術的な知識に自信がない場合は、次のコマンドでインストール先を確認できます。

   which mcp-proxy
   

   これにより、mcp-proxy バイナリへのフルパスが出力されます（例：/home/user/.local/bin/mcp-proxy）。

MCP Proxy サーバーの起動

Motion API キーと、このサーバーの main.ts ファイルのパスを指定してプロキシサーバーを起動します。

/path/to/mcp-proxy --port 8080 --env MOTION_API_KEY "your_motion_api_key_here" npx tsx /path/to/your/motion_mcp_server/main.ts

重要な置き換え項目：

• /path/to/mcp-proxy を which mcp-proxy コマンドで取得した実際のパスに置き換えます
• "your_motion_api_key_here" を実際の Motion API キーに置き換えます
• /path/to/your/motion_mcp_server/main.ts を、このサーバーの main.ts ファイルの絶対パスに置き換えます

例：

/home/user/.local/bin/mcp-proxy --port 8080 --env MOTION_API_KEY "mt_abc123xyz789" npx tsx /home/user/projects/motion-mcp-server/main.ts

MCP クライアントの設定

プロキシサーバーが起動したら、サポートされている接続タイプに応じて MCP クライアントを設定します。

ストリーミング可能な HTTP 接続の場合

クライアントの MCP 設定ファイルに、次の設定を追加します。

{
  "mcpServers": {
    "motion-mcp": {
      "type": "mcp",
      "url": "http://localhost:8080/mcp",
      "note": "Motion MCP server via HTTP proxy"
    }
  }
}

SSE（Server-Sent Events）接続の場合

クライアントの MCP 設定ファイルに、次の設定を追加します。

{
  "mcpServers": {
    "motion-sse": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "note": "Motion MCP server via SSE proxy"
    }
  }
}

MCP Inspector によるテスト

MCP Inspector ツールを使用して、プロキシのセットアップをテストできます。

1. テスト用の設定ファイルを作成します（例：mcp-test-config.json）。上記の設定のいずれかを使用してください。

2. Inspector を実行します。

   npx @modelcontextprotocol/inspector --config /path/to/mcp-test-config.json --server motion-mcp
   

   （SSE の設定をテストする場合は --server motion-sse を使用してください）

3. Inspector にアクセスします。 Inspector が提示する URL（通常は http://127.0.0.1:6274）をウェブブラウザーで開き、プロキシ経由で Motion ツールをテストします。

重要な注意事項

• プロキシを起動したままにする： クライアントが Motion MCP サーバーを使用している間は、mcp-proxy サーバーを起動したままにする必要があります。プロキシを停止すると、クライアントは Motion ツールとの接続を失います。

• ポートの競合： ポート 8080 がすでに使用されている場合は、別のポート（例：--port 8081）を選択し、それに応じてクライアント設定の URL を更新してください。

• レート制限： プロキシを使用する場合も、同じレート制限ルールが適用されます。Motion API の 3 分あたり 12 回という制限は、接続方法に関係なく適用されます。

• セキュリティ： プロキシサーバーはローカルで実行され、HTTP エンドポイントを公開します。セキュリティ要件に適したファイアウォール設定になっていることを確認してください。

AI を Motion に接続するその他の方法

Zapier も Motion 用の MCP 統合を提供していることにご留意ください。こちらから利用できます：https://zapier.com/mcp/motion。これにより、Zapier プラットフォームを通じて AI アシスタントを Motion に接続し、Zapier がすでに提供している豊富なアプリ接続を活用できます。

主な違いと考慮事項：

• Zapier のプラットフォーム： Zapier のインフラストラクチャに依存しており、一定の無料利用上限を超えると有料プランが必要になる場合があります（Zapier によると、同社の MCP 統合は、1 時間あたり 40 回、または 1 か月あたり 300 回などの一定のレート制限内であれば、個人ユーザーは無料で利用できます）。
• このサーバー（オープンソース）： このリポジトリで提供されるサーバーはオープンソースで、セルフホスト可能です。つまり：
  • ベンダーロックインなし： コードとデプロイを完全に制御できます。
  • コスト： 無料で使用でき、費用が発生するのは独自のホスティング（必要な場合）と Motion API の利用分のみです。
  • カスタマイズ： 必要に応じて、このサーバーの機能を直接変更・拡張できます。

私たちの知る限り、Zapier の提供するものを除けば、このリポジトリは Motion API との直接統合に特化した、独自のオープンソース MCP サーバーを提供しています。

レート制限

このサーバーは、Motion API の 3 分間のローリングウィンドウあたり 12 回という上限を超えないよう、Motion API に対する自動レート制限を実装しています。レートリミッターは次の処理を行います：

• Motion API エンドポイントに対するすべての API 呼び出しを追跡します。
• 3 分あたり 12 回の制限を超える呼び出しをブロックします。
• 呼び出しがブロックされた場合、待ち時間を明確に通知します。
• ローカル SQLite データベース（.data/motion_api_ratelimit.sqlite）を使用して、サーバー再起動後もレート制限の状態を保持します。

レート制限エラーについて

この MCP サーバーを AI アシスタント（Claude Desktop や Cursor など）と併用しているときに、Motion API への呼び出しがサーバーのレートリミッターによってブロックされると、AI アシスタントに構造化されたエラーメッセージが返されます。AI アシスタントを利用しているユーザーには、通常、このエラーがチャット画面でアシスタントから伝えられます。

レート制限エラーメッセージの例（ツール呼び出しの戻り値）：

{
  "error": "Rate Limit Exceeded",
  "details": "Motion API rate limit reached. Please wait X seconds before trying again.",
  "waitTimeSeconds": X 
}

レート制限が発生したときに、AI アシスタントのインターフェース（Claude Desktop など）でどのように表示されるかを以下に示します。アシスタントは待ち時間を含むサーバーのエラーを伝えます。

キャプション：Motion MCP サーバーへのツール呼び出しを繰り返した後、AI アシスタントのインターフェースにレート制限エラーが表示される例。

AI アシスタントの応答方法：

MCP ツールと連携する AI アシスタントの多くは、このような構造化エラーを理解できるように設計されています。

1. ユーザーへの通知： AI アシスタントは、一時的なレート制限のため操作を完了できなかったことを伝え、必要な待ち時間を知らせます（例：「現在、Motion API のレート制限に達しているため実行できません。X 秒後にもう一度お試しください。」）。
2. AI による即時再試行なし： アシスタントは、コマンドをすぐに再試行してはいけません。waitTimeSeconds を守る必要があります。
3. ユーザーへの案内： AI のメッセージに基づき、同じコマンドまたは別の Motion 関連コマンドを AI アシスタントに実行させる前に、指定された時間以上待ってください。

この仕組みによって、サーバーは Motion API の制限を守りながら、AI アシスタントを通じて明確なフィードバックを提供できるため、よりスムーズに利用できます。

クレジットと謝辞

この Motion MCP Server は、Updab AB の SpecToMCP ツールを使用して初期のひな形が作成されました。

• SpecToMCP は、OpenAPI（Swagger）仕様から基盤となる Model Context Protocol サーバーを生成する、非常に便利なツールです。堅牢な出発点を提供し、その後の反復開発を可能にしたことで、このプロジェクトの初期開発が大幅に加速しました。
• SpecToMCP はこちらで確認でき、詳細もご覧いただけます：https://spectomcp.updab.com/

開発者コミュニティにこのような貴重なリソースを提供してくださった Updab に感謝いたします。

トラブルシューティング

• ERR_DLOPEN_FAILED / NODE_MODULE_VERSION の不一致： これは最もよくある問題で、特に better-sqlite3 で発生します。依存関係のインストール時（および better-sqlite3 のコンパイル時）に使用した Node.js のバージョンと、MCP クライアント（例：Claude Desktop）がサーバーの実行に使用している Node.js のバージョンが異なることを意味します。

  • 解決方法： npm install の前に Node.js のバージョンを揃えるため、Setup セクションの Step 2 に注意深く従ってください。npm rebuild better-sqlite3 --update-binary を実行するか、node_modules と package-lock.json を削除し、正しい Node.js のバージョンを有効にしてから npm install を再実行する必要がある場合があります。

• API キーが見つからない／無効： MOTION_API_KEY 環境変数が正しく設定されていること（Setup の Step 4 または MCP クライアントの設定に従っていること）、およびキー自体が有効で、取り消されていないことを確認してください。

• データベースの問題（.data/motion_api_ratelimit.sqlite）： SQLite データベースは、プロジェクト内の .data/ ディレクトリに保存されます。このディレクトリとファイルは自動的に作成されます。

  • 破損が疑われる場合（例：Node.js のバージョンが正しいことを確認した後も、データベース関連のエラーが続く場合）は、motion_api_ratelimit.sqlite ファイルを削除してみてください。サーバーは次回の起動時にファイルを再作成します。警告：これによりレート制限の履歴がリセットされます。以前にレート制限を受けていた場合、呼び出しが一時的に急増する可能性があります。

• MCP クライアントの設定におけるパスの問題： MCP クライアントの設定（例：claude_desktop_config.json）にある main.ts へのパスが、お使いのシステムで正しい絶対パスになっていることを再確認してください。

コントリビューション

Issue や機能リクエストを歓迎します！このリポジトリの GitHub Issue トラッカーから送信してください。コードのコントリビュートをご希望の場合は、提案する変更について話し合うため、まず Issue を作成してください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。