tsheets-mcp

TSheets (QuickBooks Time) 用のMCPサーバー — Intuitのタイムトラッキング、スケジューリング、PTOプラットフォーム。TSheets REST API v1の全公開エンドポイントをMCPツールとして公開します。

概要

• ステートレスなHTTPサービス。認証情報は一切永続化されません — 各リクエストが独自のアクセストークンをヘッダーで提供し、その単一リクエストの期間のみ使用されます。

• 同時リクエストをサポート。リクエストごとの認証情報の分離は、グローバル/共有クライアントインスタンスではなく、Pythonのcontextvarsを使用して行われます。

• エントリポイント: POST /mcp (MCPプロトコル) と GET /health (ヘルスチェック)。

• デフォルトポート: 8080 (MCP_HTTP_PORTで設定可能)。

• TSheets APIにはパステンプレートパラメータは存在しません — すべての識別子 (ids、user_idなど) は、単一リソースの参照であってもクエリ文字列パラメータとして渡されます。これは実際のAPI設計上の特徴であり、このサーバーによる簡略化ではありません。

Related MCP server: Timesheet MCP Server

スコープ

15ツール。元の85ツールのフルAPIビルド (2026-08-04) から削減。このベンダーに対するMSPbots自身の保存済み統合設定は、正確に6エンドポイント (Effective Settings、Jobcodes、Users、Customfielditem User Filters、Timesheets、Custom Fields — すべてGET、読み取り専用) を呼び出します。「実際の使用状況 + 同カテゴリのコアCRUD」のスコープ決定に従い、このビルドは正確にその6カテゴリを完全な形で保持します — effective_settings (1、読み取り専用、このリソースにはCRUD動詞は存在しません)、custom_field_item_user_filters (1、同様)、jobcodes (3: 作成/取得/更新)、users (3: 作成/取得/更新)、timesheets (4: 作成/取得/更新/削除)、custom_fields (3: 作成/取得/更新) — 合計15ツール。元の85ツールビルドの他のすべてのカテゴリ (Reports、Files、Time Off Requests (+ Entries)、Schedule Events (+ Calendars)、Reminders、Projects (+ Notes/Activities/Activity Replies/Activity Read Times)、Notifications、Locations (+ Maps)、Jobcode Assignments、Groups、Estimates (+ Items)、Custom Field Items (+ Filters + Jobcode Filters)、Geolocations、Timesheets Deleted、Managed Clients、Last Modified、Invitations、Geofence Configs、Current User — 28カテゴリ、約70ツール) は、MSPbotsが使用していないため完全に削除されました。

保持されたツールのソースデータは、元々TSheetsドキュメントのGitHubリポジトリ (https://github.com/tsheetsteam/api_docs) をクローンし、各エンドポイントのMarkdown/ERBパーシャルファイル (source/includes/APIReference/<Category>/_*.md.erb) を解析して、HTTPメソッド、パス、パラメータテーブルを抽出することで取得されました — これはこのプログラムの他の大規模APIベンダー (ConnectSecure、Dynu、Jira Data Center、Opsgenie) で使用されているものと同じ構造化抽出→コード生成アプローチです。削除されたカテゴリが後で必要になった場合、同じソースを同じ方法で再解析できます。

認証

TSheetsは、ベンダー自身のOAuth/APIアプリフローを介して取得される静的アクセストークンを使用します (MSPbotsの内部KB記事を参照。統合設定からリンクされています)。MSPbots自身の統合規約では、このトークンをAuthorization: Bearer <accessToken>として送信します。これはTSheets自身の文書化された形式と一致し、このサーバーはそのまま転送します。

ヘッダー 認証パラメータ説明

ヘッダーがない場合は401を返します:

{
  "error": "Missing credentials",
  "message": "This server requires the X-TSheets-Access-Token header",
  "required_headers": ["X-TSheets-Access-Token"],
  "optional_headers": []
}

環境変数

MCPエンドポイント

• POST /mcp — MCPプロトコル (ストリーミング可能なHTTPトランスポート)

• GET /health — ヘルスチェック。正確に{"status": "ok"}を返します。これは純粋なローカルプローブです — TSheets APIを呼び出さないため、TSheetsの障害でコンテナが不健全とマークされることはありません。

エラーとページネーション

• ツールエラーは、インバンドJSONエンベロープとして返されます (例外やプロトコルレベルのエラーではありません): {"error": {"code": "...", "message": "...", "retryable": true|false}}。codeはnot_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_errorのいずれかで、アップストリームのHTTPステータスからマッピングされます。

• TSheets APIへの送信呼び出しは、5秒の接続 / 30秒の読み取りタイムアウトを使用し、429/5xxでは上限付き指数バックオフで最大3回再試行し (Retry-Afterを尊重)、プロセス存続期間中単一の接続プールを再利用します。

• すべてのretrieve_*ツールのlimitパラメータはデフォルトで50で、呼び出し元がそれ以上を要求した場合、TSheets自身の文書化されたページあたりの最大値200にクランプされます (TSheets自身のAPIもデフォルト/最大が200なので、両方の上限はここで一致します)。

ツール一覧

ツール名はtsheets_<category>_<operation>で、ソースドキュメントの各操作の## Headingから派生しています (例: timesheetsカテゴリの「Retrieve Timesheets」→ tsheets_timesheets_retrieve_timesheets)。いくつかのretrieveフィルタパラメータは「(X、Y、またはZが設定されていない限り) 必須」と文書化されています — これは単一の必須Pythonパラメータとしてきれいに表現できないN個中の1個の要件であるため、これらはオプションとしてモデル化され、OR制約はツール自身のdocstringに明記されています。create/updateエンドポイントのbodyパラメータは汎用のdictとして受け入れられます — TSheets自身の規約では、これらを{"data": [ {...}, ... ]} (1回の呼び出しで最大50オブジェクトの一括作成/更新) でラップし、ツールごとに文書化されています。

テスト例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-TSheets-Access-Token: <your-tsheets-access-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "tsheets_jobcodes_retrieve_jobcodes",
      "arguments": {}
    }
  }'

ライブ検証済み (2026-07-30): 最初のテスト用アクセストークンは期限切れであることが判明しました（401 invalid_grant、直接のcurlでも同一であることを確認 — その実行で何が検出されたかについては下記のバグメモを参照）。その後、新たに発行されたアクセストークンがこの実行中サーバーを通じてエンドツーエンドでテストされ、実際のアカウントデータが返されました：tsheets_current_user_retrieve_the_current_user は実際の現在のユーザーレコード（名前、権限、PTO残高）と補足のジョブコードデータを返し、tsheets_jobcodes_retrieve_jobcodes（MSPbots自身が設定した6つのエンドポイントの1つに一致）は実際のジョブコードレコードを返しました。どちらも、リクエスト/認証/レスポンスのパイプライン全体がライブAPIに対して正しく機能することを確認しています。

セルフテスト中に修正されたバグ: 初期の_raise_for_statusエラーパーサーは、TSheetsが常にエラー詳細を{"error": {"message": "..."}}としてネストすると想定していましたが、TSheetsは実際には認証失敗時にOAuthスタイルのフラットな{"error": "invalid_grant", "error_description": "..."}を返します — 文字列"invalid_grant"に対して.get()を呼び出すと、'str' object has no attribute 'get'でクラッシュしました。これは、このサーバーが完成と見なされる前に、最初の（期限切れの）テストトークンを使用して検出・修正されました。

APIリファレンス

• 概要: https://tsheetsteam.github.io/api_docs/

• ソース（公式Postmanコレクションを含む）: https://github.com/tsheetsteam/api_docs

既知のギャップ

• 2026-08-04に85ツールから15ツールに削減。 当初のビルドは、以前のスコープ決定に基づき、34カテゴリにわたる完全な公開APIをカバーしていました。その後のスコープ決定により、MSPbotsが実際に使用している6カテゴリのみに削減されました（すべて完全に保持 — 各カテゴリが数ツールを超えなかったため、カテゴリごとの削減は不要でした）— 削除された28カテゴリ（約70ツール）の完全なリストについては、上記のスコープセクションを参照してください。削除されたカテゴリが後で必要になった場合、ソースドキュメント（https://github.com/tsheetsteam/api_docs）を、保持されたツールが生成されたのと同じ方法で再解析できます。

• tsheets_timesheets_delete_timesheets は、ベンダーの公式ドキュメントによるとタイムシートレコードを完全に削除します — 破壊的/不可逆的として扱い、呼び出す前に人間による確認を行ってください。他の保持されているcreate/updateツールも、実際のTSheetsデータ（ジョブコード、ユーザー、カスタムフィールド）を変更します。

• N個中1つの「必須」フィルターグループはすべて任意としてモデル化 — いくつかのRetrieveエンドポイントは、パラメータを「（X、Y、またはZが設定されていない限り）必須」と文書化しています。これを実際の制約として強制することは、単純な関数シグネチャでは表現できないため、そのようなパラメータはすべてツールシグネチャでは任意となり、OR要件は代わりにdocstringに明記されています。呼び出し元は、文書化された制約に従って少なくとも1つを提供する必要があります。そうしないと、ライブAPIがリクエストを拒否します。

• bodyパラメータは完全にモデル化されておらず、型なし（dict）です — TSheetsの公式ドキュメントにはタイプごとのフィールドバリアントが示されています（例：「通常のタイムシート」と「手動タイムシート」では、同じdata配列内で必須フィールドが異なります）。これらは固定の型付きパラメータにきれいにマッピングできません。ベンダーの公式リファレンス（上記リンク）に、リソースごとの正確なスキーマが文書化されています。