FreeloMCP

Name: FreeloMCP
Author: karlost

ローカル

github.com/karlost生産性104 週間前に更新

リポジトリ

FreeloMCP について

FreeloMCPは、Freelo API v1を通じてプロジェクトやタスクを管理する非公式コミュニティ製MCPサーバーです。プロジェクト、タスク、時間記録、請求書などを操作でき、stdioとHTTPのトランスポートに対応します。

主な機能

01Freelo API向け104ツール
02プロジェクト、タスク、サブタスクの管理
03時間、ファイル、コメント、請求書の操作
04ページネーションと高度なフィルター
05stdioとStreamable HTTPに対応

活用シーン

01Freeloのタスク検索と絞り込み
02プロジェクト作成とメンバー管理
03時間記録と作業レポートの確認
04HTTPクライアントからFreeloにアクセス

MCP 対応

Freelo API v1のプロジェクト、タスク、時間記録などの機能を、MCPクライアント向けのツールとして公開します。stdio、Streamable HTTP、非推奨のSSEに対応し、APIキーによるHTTP Basic Authenticationを使用します。

#freelo #mcp #apimodelcontextprotocol #cline

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "FreeloMCP": {
      "command": "npx",
      "args": [
        "-y",
        "freelo-mcp"
      ],
      "env": {
        "FREELO_EMAIL": "<FREELO_EMAIL>",
        "FREELO_API_KEY": "<FREELO_API_KEY>"
      }
    }
  }
}

起動コマンドnpx -y freelo-mcp

設定が必要な環境変数

FREELO_EMAIL

FREELO_API_KEYシークレット

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npmfreelo-mcpstdio

ツール

104

掲載時のツール一覧 · 3 週間前に更新

このツールにパラメーターはありません。

詳細

Freelo MCP サーバー（非公式）

注意: これは非公式のコミュニティプロジェクトであり、Freelo 社による直接のサポートはありません。

Freelo API v1 用 MCP サーバー — Freelo API と通信するための Model Context Protocol サーバーの完全な実装です。Freelo はチェコのプロジェクト管理・タスク管理サービスです。

✨ 特長

🚀 104 個の MCP ツールで Freelo API v1 の 100% をカバー
✅ 十分にテスト済み — 207 件のユニットテスト + 82 件の実 API テスト
🔧 本番環境対応 — 既知のバグをすべて修正済み
📊 スマートフィルタリング — ページネーションと高度なフィルターに対応
🔒 安全 — API キーによる HTTP Basic Authentication
🎯 最適化済み — 大規模なデータセット向けのトークン制限を修正
📝 完全なドキュメント — すべてのツールについて詳細に説明
🏷️ MCP アノテーション — 動作に関するヒント（readOnly、destructive、idempotent）を自動付与
📋 OutputSchema — すべての API 応答を検証する Zod スキーマ
🧩 モジュール型アーキテクチャ — ツールを 19 のモジュールに整理

📊 プロジェクトの状況

指標	値
MCP ツール合計	104
動作するツール	100%
修正済みのバグ	16/16 (100%)
API カバレッジ	Freelo API v1 の 100%
ユニットテスト	207（205 件成功、2 件スキップ）
実 API テスト	82 件成功、0 件失敗
テスト状況	✅ 検証完了

🚀 クイックスタート

NPX によるインストール（推奨）

Freelo MCP を使い始める最も簡単な方法は npx を使うことです。インストールは不要です！

1️⃣ Claude Desktop（Anthropic Desktop）の場合

設定ファイルを探します：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Freelo MCP サーバーを設定に追加します：

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}

Claude Desktop を再起動します
確認します：
- Claude Desktop の下部パネルに 🔌 アイコンが表示されます
- 「Freelo のプロジェクトを表示して」と試してください

2️⃣ Claude Code（CLI）の場合

コマンド 1 つで MCP サーバーを追加します：

claude mcp add freelo-mcp \
  --env [email protected] \
  --env FREELO_API_KEY=VAS_API_KLIC \
  --env FREELO_USER_AGENT="FreeloMCP/3.0.0 ([email protected])" \
  -- npx -y freelo-mcp

重要： -- 区切り文字は、Claude CLI のオプションと MCP サーバーのコマンドを分けます！

接続を更新します：

/mcp

確認します：

Claude Code で「Freelo のプロジェクトを表示して」と試してください。

別のインストール方法 — Git clone

開発する場合や、コードを変更する場合に使用します：

# Klonování repozitáře
git clone https://github.com/karlost/FreeloMCP.git
cd FreeloMCP

# Instalace závislostí
npm install

# Vytvoření .env souboru
cat > .env << EOF
[email protected]
FREELO_API_KEY=VAS_API_KLIC
FREELO_USER_AGENT=FreeloMCP/3.0.0 ([email protected])
EOF

# Spuštění MCP serveru
node mcp-server.js

ローカルインストールでの Claude Desktop の設定：

{
  "mcpServers": {
    "freelo": {
      "command": "node",
      "args": ["/absolutni/cesta/k/FreeloMCP/mcp-server.js"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}

ローカルインストールでの Claude Code の設定：

claude mcp add freelo-mcp \
  --env [email protected] \
  --env FREELO_API_KEY=VAS_API_KLIC \
  --env FREELO_USER_AGENT="FreeloMCP/3.0.0 ([email protected])" \
  -- node /absolutni/cesta/k/FreeloMCP/mcp-server.js

🚀 トランスポートの選択肢

Freelo MCP サーバーは 3 種類のトランスポートプロトコルに対応しています：

1. Stdio トランスポート（デフォルト — CLI ツール）

Claude Desktop、Claude Code、Cline、その他の CLI ベースの MCP クライアント向けです。

使用方法：

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0"
      }
    }
  }
}

2. Streamable HTTP トランスポート（⭐ HTTP クライアントに推奨）

Web アプリケーション、n8n、ElevenLabs Agents、リモートアクセス向けの、最新の MCP 準拠 HTTP トランスポートです。

HTTP サーバーの起動：

# Základní použití
npm run mcp:http

# S vlastním portem
PORT=8080 npm run mcp:http

# Nebo přes npx
PORT=8080 npx -y freelo-mcp-http

エンドポイント： http://localhost:3000/mcp/v1/endpoint

必須の HTTP ヘッダー：

MCP-Protocol-Version: 2025-03-26
Accept: text/event-stream（GET リクエストの場合）
Mcp-Session-Id: <session-id>（初期化後）

ヘルスチェック： GET http://localhost:3000/health

環境設定：

PORT=3000
[email protected]
FREELO_API_KEY=VAS_API_KLIC
FREELO_USER_AGENT=FreeloMCP/3.0.0

3. SSE トランスポート（⚠️ 非推奨）

レガシーの Server-Sent Events トランスポートです。代わりに Streamable HTTP を使用してください。

npm run mcp:sse

エンドポイント： http://localhost:3000/sse

⚠️ 警告： SSE トランスポートは、MCP 仕様 2025-03-26 で非推奨になりました。Streamable HTTP トランスポートに移行してください。詳しくは MIGRATION_HTTP.md をご覧ください。

📡 トランスポートの比較

機能	Stdio	Streamable HTTP	SSE（レガシー）
ユースケース	CLI ツール	HTTP／Web クライアント	レガシーサポート
ステータス	✅ アクティブ	✅ 推奨	⚠️ 非推奨
セッション管理	N/A	✅ はい	✅ はい
MCP 標準	✅ はい	✅ はい（2025-03-26）	❌ 旧仕様
エンドポイント	stdio	`/mcp/v1/endpoint`	`/sse`
プロトコル	stdin/stdout	HTTP GET/POST	Server-Sent Events
用途	デスクトップアプリ	n8n、Web アプリ、リモート	レガシーからの移行

その他の MCP クライアントの設定

3️⃣ Cline（VS Code 拡張機能）

Cline をインストールした状態で VS Code を開きます
Cline で MCP Settings を開きます（ハンバーガーアイコン → MCP Settings）
設定ファイルを編集します：

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}

VS Code を再起動するか、ウィンドウを再読み込みします（Cmd/Ctrl + Shift + P → "Reload Window"）
確認： Cline のチャットで「Freelo のプロジェクトを表示して」と試します

4️⃣ Windsurf（Codeium）

Windsurf は Claude Desktop と同じ形式で MCP をサポートしています。

設定ファイルを見つけます：
- macOS：~/Library/Application Support/Windsurf/settings/mcp_config.json
- Windows：%APPDATA%\Windsurf\settings\mcp_config.json
- Linux：~/.config/Windsurf/settings/mcp_config.json
設定を追加します：

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}

Windsurf を再起動します

5️⃣ Zed Editor

Zed Settings を開きます（Cmd/Ctrl + ,）
「Language Models」→「Configure MCP Servers」に移動します
設定を追加します：

{
  "freelo": {
    "command": "npx",
    "args": ["-y", "freelo-mcp"],
    "env": {
      "FREELO_EMAIL": "[email protected]",
      "FREELO_API_KEY": "VAS_API_KLIC",
      "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
    }
  }
}

Zed を再起動します

6️⃣ Continue.dev（VS Code／JetBrains）

Continue の設定ファイルを開きます：
- VS Code：ホームディレクトリにある .continue/config.json
- JetBrains：同じ場所
MCP サーバーを追加します：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "freelo",
        "command": "npx",
        "args": ["-y", "freelo-mcp"],
        "env": {
          "FREELO_EMAIL": "[email protected]",
          "FREELO_API_KEY": "VAS_API_KLIC",
          "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
        }
      }
    ]
  }
}

IDE を再起動します

7️⃣ LibreChat

LibreChat（セルフホスト型の ChatGPT 代替サービス）では：

librechat.yaml を編集します：

mcpServers:
  - name: freelo
    command: npx
    args:
      - "-y"
      - "freelo-mcp"
    env:
      FREELO_EMAIL: [email protected]
      FREELO_API_KEY: VAS_API_KLIC
      FREELO_USER_AGENT: "FreeloMCP/3.0.0 ([email protected])"

LibreChat コンテナーを再起動します

8️⃣ n8n（ワークフロー自動化）

n8n では stdio ではなく、SSE（Server-Sent Events）トランスポートが必要です。Freelo MCP は専用の SSE サーバーを提供しています。

1. SSE サーバーを起動します：

npx を使ってローカルで起動：

npx -y freelo-mcp-sse

または、git clone 後に npm スクリプトを使用：

npm run mcp:sse

または、独自のポートを指定：

PORT=8080 npx -y freelo-mcp-sse

2. n8n で設定します：

n8n ワークフローに MCP Client Tool ノードを追加します
MCP Client の設定で、新しい認証情報を作成します：
- トランスポートタイプ： SSE
- SSE エンドポイント URL： http://localhost:3000/sse
- メッセージエンドポイント URL： http://localhost:3000/message
接続すると、104 個すべての Freelo ツールにアクセスできます

3. ヘルスチェック：

サーバーが稼働していることを確認します：

curl http://localhost:3000/health

応答：

{
  "status": "ok",
  "service": "freelo-mcp-sse",
  "version": "3.0.0",
  "activeConnections": 0,
  "endpoints": {
    "sse": "/sse",
    "messages": "/message",
    "health": "/health"
  }
}

4. Docker でのデプロイ：

本番環境で使用する場合は、Docker コンテナーを作成できます：

FROM node:18-alpine
WORKDIR /app
RUN npm install -g freelo-mcp
ENV [email protected]
ENV FREELO_API_KEY=VAS_API_KLIC
ENV FREELO_USER_AGENT="FreeloMCP/3.0.0 ([email protected])"
ENV PORT=3000
EXPOSE 3000
CMD ["freelo-mcp-sse"]

docker build -t freelo-mcp-sse .
docker run -p 3000:3000 freelo-mcp-sse

注意事項：

SSE サーバーは複数の同時接続をサポートしています
各接続には個別のセッション ID が割り当てられます
クライアントが切断されると、セッションは自動的にクリーンアップされます
すべてのオリジンで CORS が許可されています

📚 利用可能な MCP ツール

カテゴリ別の概要（104 ツール）

カテゴリ	数	説明
Tasks	22	タスクの CRUD、リマインダー、公開リンク、見積もり
Projects	13	プロジェクト管理、テンプレート、アーカイブ
Custom Fields	14	カスタムフィールド、列挙型オプション、値
Labels	9	ラベルの作成、編集、管理
Users	9	ユーザー管理、不在設定、招待
Invoices	6	請求、レポート、ラベル付け
Tasklists	6	タスクリスト、ワーカー、テンプレートの管理
Work Reports	5	作業レポートの CRUD
Notes	5	プロジェクト内のメモの CRUD
Time Tracking	4	時間計測の開始／停止、編集
Files	3	ファイルのアップロード、ダウンロード、一覧表示
Comments	3	タスクとファイルへのコメント
Notifications	3	通知の取得と管理
Pinned Items	3	プロジェクト内のピン留め項目
Subtasks	3	サブタスクの作成と管理
Filters	3	タスク用カスタムフィルター
Search	1	Elasticsearch 全文検索
Events	1	イベント履歴
States	1	状態の取得（active、archived など）

🔥 よく使われるツール

Projects（18 ツール）

get_projects - 自分が所有するアクティブなプロジェクトを取得
get_all_projects - すべてのプロジェクト（自分が所有するものと共有されたもの）をページネーション付きで取得
get_project_details - ワーカーとタスクリストを含むプロジェクトの詳細
get_invited_projects - 招待されたプロジェクト
get_archived_projects - アーカイブ済みプロジェクト
get_template_projects - フィルター付きのテンプレートプロジェクト
get_user_projects - 特定のユーザーのプロジェクト
get_project_workers - プロジェクトのワーカー一覧
get_project_manager_of - 自分が PM を務めるプロジェクト
get_project_tasklists - プロジェクト内のすべてのタスクリスト
create_project - 新しいプロジェクトを作成
create_project_from_template - テンプレートから作成
archive_project - プロジェクトをアーカイブ
activate_project - プロジェクトをアクティブ化
delete_project - プロジェクトを削除
invite_users_by_email - メールでユーザーを招待
invite_users_by_ids - ID でユーザーを招待
remove_workers - プロジェクトからワーカーを削除

Tasks（19 ツール）- 高度なフィルター付き

一覧表示と詳細：

get_all_tasks - 14 個のフィルターを使ってすべてのタスクを取得：
- search_query - 全文検索
- state_id - 状態別（active、finished）
- projects_ids - プロジェクト別フィルタリング（配列）
- tasklists_ids - タスクリスト別（配列）
- order_by - 並べ替え（priority、name、date_add、date_edited_at）
- order - 順序（asc、desc）
- with_label / without_label - ラベル別
- no_due_date - 期限なし
- due_date_range - 期限の範囲
- finished_overdue - 期限後に完了
- finished_date_range - 完了日の範囲
- worker_id - ワーカー別
- p - ページネーション（0 から）
get_tasklist_tasks - 特定のタスクリスト内のタスク
get_finished_tasks - 完了済みタスク
get_task_details - タスクの詳細情報
get_task_description - タスクの説明

CRUD 操作：

create_task - タスクを作成
create_task_from_template - テンプレートから作成
edit_task - タスクを編集
update_task_description - 説明を更新
move_task - 別のタスクリストに移動
finish_task - 完了
activate_task - アクティブ化
delete_task - 削除

高度な機能：

create_task_reminder - リマインダー（✅ 修正済み）
delete_task_reminder - リマインダーを削除
get_public_link - 公開リンク
delete_public_link - リンクを削除
set_total_time_estimate - 時間の見積もり（Premium - 未テスト）
delete_total_time_estimate - 見積もりを削除（Premium - 未テスト）
set_user_time_estimate - ユーザー向けの見積もり（Premium - 未テスト）
delete_user_time_estimate - ユーザーの見積もりを削除（Premium - 未テスト）

Files（3 ツール）- アップロードとダウンロード

- `get_all_files` - フィルターを使用したファイル一覧： - `projects_ids` - プロジェクト別 - `type` - 種類（directory、link、file、document） - `p` - ページネーション

upload_file - ファイルのアップロード（最大 100MB）
- パラメーター filePath - ローカルファイルへのパス（大きなファイルの場合に推奨）
- パラメーター fileData - Base64 エンコードされたファイル（小さなファイル／メモリ内のデータ向け）
- パラメーター fileName - ファイル名（fileData の場合は必須、filePath の場合は任意）
download_file - UUID によるファイルのダウンロード

時間管理と作業レポート（7 ツール）

時間管理：

start_time_tracking - 時間計測の開始
stop_time_tracking - 時間計測の停止
edit_time_tracking - アクティブな時間計測の編集

作業レポート：

get_work_reports - フィルターを使用した作業レポートの取得：
- projects_ids - プロジェクト別
- users_ids - ユーザー別
- tasks_labels - ラベル別
- date_reported_range - 日付範囲
create_work_report - レポートの作成
update_work_report - レポートの更新
delete_work_report - レポートの削除

カスタムフィールド（11 ツール）- プレミアム機能

⚠️ 注記： カスタムフィールドは Freelo のプレミアム機能です（402 Payment Required）。プランの制限により、これらのツールは十分にテストされていません。

get_custom_field_types - フィールドの種類（text、number、date、bool、enum、link）
get_custom_fields_by_project - プロジェクト内のフィールド
create_custom_field - フィールドの作成（✅ 修正済み - enum validation）
rename_custom_field - 名前の変更
delete_custom_field - 削除
restore_custom_field - 復元
add_or_edit_field_value - フィールドの値
add_or_edit_enum_value - Enum の値
delete_field_value - 値の削除
get_enum_options - Enum の選択肢
create_enum_option - Enum の選択肢を新規作成

その他のカテゴリー

タスクリスト（5）：

get_project_tasklists, get_tasklist_details, get_assignable_workers
create_tasklist, create_tasklist_from_template（✅ 修正済み）

ユーザー（6）：

get_users, get_out_of_office, set_out_of_office（✅ 修正済み）
delete_out_of_office, invite_users_by_email, invite_users_by_ids（✅ 修正済み）

サブタスク（2）：

create_subtask, get_subtasks

コメント（3）：

create_comment, edit_comment, get_all_comments（フィルター + ページネーションあり）

ラベル（9）：

create_task_labels, add_labels_to_task, remove_labels_from_task, find_available_labels
edit_label, delete_label, add_label_to_project, remove_label_from_project

請求書（4）：

get_issued_invoices, get_invoice_detail, download_invoice_reports, mark_as_invoiced

通知（3）：

get_all_notifications（ページネーションあり）, mark_notification_read, mark_notification_unread

ノート（4）：

create_note, get_note, update_note, delete_note

ピン留めした項目（3）：

get_pinned_items, pin_item（✅ 修正済み）, delete_pinned_item

イベント（1）：

get_events - 高度なフィルターを使用した履歴（7 個のパラメーター + ページネーション）

フィルター（3）：

get_custom_filters, get_tasks_by_filter_uuid, get_tasks_by_filter_name

ステータス（1）：

get_all_states - すべてのステータスを取得（active、archived、template、finished）

検索（1）：

search_elasticsearch - エンティティを横断する全文検索

🤖 AI エージェントガイド

AI エージェント（Claude、ChatGPT など）で Freelo MCP を効果的に使用するには、AI_GUIDE.md をお読みください。

ガイドには以下が含まれます：

✅ クイックスタートワークフロー - よく使われるワークフロー
🔄 データフローパターン - ツールを適切に連携する方法
🎯 ツール選択ガイド - どのツールをいつ使用するか
💡 ベストプラクティス - AI エージェント向けの最適化とヒント
📊 一般的なワークフロー - よくあるタスク向けのすぐに使えるテンプレート
⚠️ エラー処理 - よくある問題の解決方法

AI エージェント向け： AI_GUIDE.md には、MCP 経由で Freelo API を最大限効率的に利用するための、体系的な手順、コード例、ワークフローパターンが記載されています。

🔧 修正済みのバグと改善

バージョン 2.0.0 - 完全な検証と修正

トークン制限の修正（4 ツール）：

✅ get_all_tasks - 14 個のフィルターパラメーターとページネーションを追加
✅ get_events - 7 個のフィルターパラメーターとページネーションを追加
✅ get_all_comments - 5 個のフィルターパラメーターとページネーションを追加
✅ get_all_files - 3 個のフィルターパラメーターとページネーションを追加

API 統合の修正（16 件のバグを修正）：

✅ create_task_reminder - date → remind_at に変換
✅ invite_users_by_ids - project_id → projects_ids（配列）に変更
✅ set_out_of_office - データを {out_of_office: {...}} でラップ
✅ pin_item - デフォルトのリンク値を null ではなく '#' に設定
✅ create_tasklist_from_template - nested object ではなくフラットな構造に変更
✅ upload_file - 'form-data' package から FormData のインポートを追加
✅ create_custom_field - is_required を boolean ではなく enum('yes','no') に変更
✅ create_comment - パラメーター 'description' → 'content' を修正
✅ edit_comment - API 用の正しいデータ構造に修正
✅ create_subtask - assignedTo パラメーターを修正
✅ create_task - パラメーターを完全に検証

v3.0.0 での新しい修正： 12. ✅ add_labels_to_task - API では { uuid } ではなく { id } を使用 13. ✅ remove_labels_from_task - 同じ修正 14. ✅ create_comment - 添付ファイルを attachments ではなく files: [{ uuid }] で指定 15. ✅ edit_comment - 添付ファイルを { download_url } ではなく files: [{ uuid }] で指定 16. ✅ remove_workers - users_ids を integer array にし、users_emails キーを使用

💡 使用例

基本的なプロジェクト操作

// Získání všech projektů
await get_all_projects()

// Detail konkrétního projektu
await get_project_details({ projectId: "197352" })

// Vytvoření nového projektu
await create_project({
  projectData: {
    name: "Nový projekt",
    currency_iso: "CZK"
  }
})

タスクとフィルターの操作

// Všechny aktivní úkoly v projektu
await get_all_tasks({
  filters: {
    projects_ids: [197352],
    state_id: 1,
    order_by: "priority",
    order: "desc",
    p: 0
  }
})

// Hledání úkolů s konkrétním štítkem
await get_all_tasks({
  filters: {
    with_label: "urgent",
    no_due_date: false,
    p: 0
  }
})

// Úkoly dokončené po termínu
await get_all_tasks({
  filters: {
    finished_overdue: true,
    finished_date_range: {
      date_from: "2025-10-01",
      date_to: "2025-10-09"
    }
  }
})

タイムトラッキングのワークフロー

// 1. Spustit tracking na úkolu
await start_time_tracking({ taskId: "25368707" })

// 2. Upravit popis
await edit_time_tracking({
  trackingData: {
    description: "Práce na feature XYZ"
  }
})

// 3. Zastavit a vytvořit work report
await stop_time_tracking()

ファイル

// Upload souboru z disku (preferováno pro velké soubory)
await upload_file({
  filePath: "/cesta/k/dokument.pdf"
})

// Upload souboru z base64 (pro malé soubory / data v paměti)
const base64Data = Buffer.from("obsah souboru").toString('base64')
await upload_file({
  fileName: "dokument.pdf",
  fileData: base64Data
})

// Listing souborů v projektu
await get_all_files({
  filters: {
    projects_ids: [197352],
    type: "file",
    p: 0
  }
})

🔒 認証

API キーの取得

Freelo にログインします
設定 → API に移動します
新しい API キーを生成します
キーをコピーし、安全に保管します

セキュリティ

⚠️ API キーを公開しないでください
⚠️ .env ファイルを Git に コミットしないでください
✅ credentials の保護には .gitignore を使用してください
✅ 本番環境では環境変数を使用してください

🧪 テスト

単体テスト

# Spuštění všech testů (207 testů, 7 test suites)
npm test

# Konkrétní test suite
npm test -- tests/mcp-tools-simple.test.js

# S code coverage
npm test -- --coverage

実 API テスト

104 個すべてのツールを対象とした、Freelo API に対する完全なテストです：

[email protected] \
FREELO_API_KEY=VAS_API_KLIC \
FREELO_USER_AGENT=freelo-mcp \
node tests/real-api-full-test.js

結果：82 件成功、0 件失敗、33 件スキップ（スキップは premium 機能、データ不足によるものです）

🐛 トラブルシューティング

MCP サーバーに接続できない

解決方法：

Node.js のバージョンが ≥ 18.0.0 であることを確認します：node --version
設定内の環境変数を確認します
Claude Code を再起動します：/mcp
ログを確認します：ps aux | grep mcp-server

エラー「Payment required (402)」

一部の機能は premium です：

Custom Fields 操作
Time estimates（set/delete）

解決方法： Freelo プランをアップグレードするか、別のツールを使用します。

トークン制限を超過

大規模なデータセットには、ページネーションを使用してください：

// Místo
await get_all_tasks()

// Použijte
await get_all_tasks({
  filters: {
    projects_ids: [specificProjectId],
    p: 0  // první stránka
  }
})

サーバーが繰り返し再起動する

理由： ES6 モジュールは Node.js プロセス内でキャッシュされます。

解決方法：

# Najděte proces
ps aux | grep "[n]ode.*mcp-server.js"

# Zabijte proces (nahraďte PID)
kill -9 PID

# Refresh v Claude Code
/mcp

📖 その他のリソース

🤝 貢献

貢献を歓迎します！

リポジトリをフォークします
feature branch を作成します（git checkout -b feature/AmazingFeature）
変更をコミットします（git commit -m 'Add AmazingFeature'）
branch をプッシュします（git push origin feature/AmazingFeature）
Pull Request を作成します

📝 変更履歴

v3.0.0 (2026-03-09) - 大規模リファクタリングと実 API の完全検証！🎯🧪

モジュラーアーキテクチャ：

🧩 19 個のツールモジュール - ツールをモノリシックな mcp-server.js から tools/ 内の個別モジュールにリファクタリング
📁 新しい構成：tools/tasks.js、tools/projects.js、tools/labels.js、tools/comments.js など
🔧 共有ユーティリティ：registerToolWithMetadata.js、paginationHelper.js、errorHandler.js

新しいツール（98 → 104）：

➕ get_note - ノートの詳細を取得
➕ change_enum_option - 列挙型オプションを編集
➕ force_delete_enum_option - 列挙型オプションを強制削除
➕ get_invoice_reports_json - 請求レポートを JSON で取得
➕ get_assignable_workers - タスクリストに割り当て可能な作業者を取得
➕ edit_label / delete_label / add_label_to_project / remove_label_from_project - ラベル管理機能一式

実 API テストで見つかったバグの修正（新たに 5 件）：

🐛 add_labels_to_task - API ではラベルに { uuid } ではなく { id } を使用
🐛 remove_labels_from_task - add_labels_to_task と同じ修正
🐛 create_comment - 添付ファイルには attachments ではなく files: [{ uuid }] を使用
🐛 edit_comment - 添付ファイルには { download_url } ではなく files: [{ uuid }] を使用
🐛 remove_workers - users_ids は整数配列、キーは users_emails

テスト：

✅ 7 つのテストスイートに 207 件のユニットテスト（205 件成功、2 件スキップ）
✅ 実際の Freelo API に対する 82 件の実 API テスト（失敗 0 件）
🧪 新しい tests/real-api-full-test.js - 104 個すべてのツールを対象とした実 API テスト
🔄 API のレート制限（429）に対する再試行ロジック
⏭️ プレミアム機能を自動スキップ（402）

v2.3.0 (2025-10-12) - MCP メタデータの完全な実装！🏷️📊

✨ 新機能： 98 個すべてのツールに MCP ツールのアノテーションと outputSchema を実装
🏷️ 動作ヒント： 各ツールに次のアノテーションを自動設定：
- readOnlyHint: true - 41 個のツールはデータの読み取りのみ（確認なしで安全に使用可能）
- destructiveHint: true - 14 個のツールはデータを削除する可能性がある（確認が必要）
- idempotentHint: true - 18 個のツールは安全に繰り返し実行可能
- openWorldHint: false - すべてのツールは Freelo API のみを使用
📊 OutputSchema： 98 個すべてのツールに、出力検証用の Zod スキーマを定義
- 公式の freelo.apib API ドキュメントに基づく
- AI エージェントがデータ構造をより適切に理解
- すべての API レスポンスで型を検証
📝 自動生成タイトル： 各ツールに、人が読みやすい名前（例：「すべてのタスクを取得」）を設定
🔧 一元管理：
- 動作ヒント用に新しい utils/toolAnnotations.js を追加
- Zod スキーマライブラリ一式として新しい utils/schemas.js を追加
- 自動適用用に新しい utils/registerToolWithMetadata.js を追加
✅ カバレッジ 100%： すべてのツールをリファクタリングし、構文エラーはありません
🧪 完全なテスト： 新しい test-annotations.js で実装の正確性を検証
📚 ドキュメント： 新しいファイル ANNOTATIONS_IMPLEMENTATION.md と TOOL_DESCRIPTIONS_ANALYSIS.md
🎯 ユーザー向けのメリット：
- Claude Desktop での UX が向上（破壊的操作に警告を表示）
- 冪等ツールの自動再試行がより安全に
- ワークフローを高速化（読み取り専用ツールは追加確認なしで使用可能）
- スキーマを使用した、より正確なレスポンス解析

v2.2.0 (2025-10-11) - AI の使いやすさを向上！🤖

✨ 重要なアップデート： 98 個すべてのツールを改善し、AI エージェントがより使いやすくなりました
📝 ツールの説明： すべてのツールに、以下を含む詳細な説明が追加されました。
- ツールの機能と使用するタイミング
- 他のツールとの関連性（ワークフローでのつながり）
- 破壊的な操作に関する警告
- プレミアム機能の表示
🔧 パラメーターの説明： すべてのパラメーターの説明が改善され、以下が含まれるようになりました。
- 形式と値の例（例：「197352」、「2025-10-11」）
- ソースツールへのリンク（必要な ID の取得元）
- 必須パラメーターと任意パラメーターの区別
📚 新しい AI_GUIDE.md： AI エージェント向けの包括的なガイドで、以下が含まれます。
- よくあるタスク向けのクイックスタートワークフロー
- データフローパターン（ツールを適切に連携させる方法）
- ツール選択ガイド（どのツールをいつ使うか）
- コード例付きの一般的なワークフロー
- ベストプラクティスとパフォーマンスのヒント
- FAQ とトラブルシューティング
🎯 結果： AI エージェントが個々のツールをどのように、いつ使うかを、これまでよりはるかによく理解できるようになりました
✅ 対応範囲： ツールの 100％をアップグレードしました（Projects、Tasks、Custom Fields、Time Tracking など）

v2.1.0 (2025-10-09) - n8n 向け SSE トランスポート！🚀

✨ 新機能： n8n やその他の HTTP クライアント向けに SSE（Server-Sent Events）トランスポートを追加しました
🌐 新しい bin コマンド：HTTP サーバーを起動する freelo-mcp-sse
📡 SSE エンドポイント：/sse、/message、/health
🔄 セッション管理による複数の同時接続をサポート
🐳 環境変数を使用した Docker 対応のデプロイ
🔧 mcp-server.js をリファクタリングし、initializeMcpServer() 関数をエクスポート
📚 n8n のセットアップと Docker デプロイに関するドキュメントを拡充
✅ 徹底的にテスト済み — SSE サーバーは安定して動作します

v2.0.5 (2025-10-09) - NPX インストールが動作！🎉

🐛 重大な修正： npx による起動を妨げていた isMainModule チェックを削除
✅ NPX インストールが完全に動作：npx -y freelo-mcp
✅ bin ファイルを簡素化（611B → 144B）
✅ MCP サーバーからすべての console.log/warn を削除（stdio プロトコルに違反していたため）
✅ モジュールの読み込み時に自動起動
✅ npx 経由でも直接起動でも動作
📝 Claude Code 向けに -- 区切り文字を追加したドキュメントに更新

v2.0.0-2.0.4 (2025-10-09)

✅ 98 個の MCP ツールを徹底的にテスト
✅ API 統合に関する 11 件のバグを修正
✅ トークン制限の修正を追加（ページネーション対応のツール 4 個）
✅ upload_file の FormData を修正
✅ カスタムフィールドの enum 検証を修正
✅ テンプレートからのタスクリスト作成を修正
✅ すべての機能で 97％以上のカバレッジ
✅ 本番環境対応のリリース
📚 7 種類の MCP クライアント向けにドキュメントを拡充

v1.0.0

🎉 初回リリース
📦 98 個の MCP ツール
🔧 REST API サーバー
📚 基本ドキュメント

📄 ライセンス

このプロジェクトはMIT ライセンスのもとでライセンスされています。

👤 作者

Chodeec (karlost)

GitHub：@karlost
NPM：freelo-mcp

⚠️ 免責事項

このプロジェクトは Freelo 社による公式サポートを受けていません。Model Context Protocol を通じて Freelo と AI アシスタントを統合するために作成された、コミュニティプロジェクトです。

🌟 プロジェクトを支援

このプロジェクトがお役に立った場合は、以下をご検討ください。

⭐ GitHub でスターを付ける
🐛 バグを報告する
💡 改善案を提案する
🤝 新機能を追加するプルリクエストを送る

Freelo コミュニティのために ❤️ を込めて作成

_{Anthropic の Claude Code の支援を受けて作成・保守}

Markdown 対応

ログインしてコメント

基本情報

ライセンス: MIT
作者: karlost
言語: node
トランスポート: stdio
掲載日: 2025年4月15日
最終更新: 4 週間前

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。