Skip to main content
Glama
deenesjakoruzh
mahrukh-n8n

Freedcamp MCP Server

by mahrukh-n8n
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Freedcamp MCPサーバー

Freedcamp REST APIをラップするModel Context Protocolサーバーです。MCP対応のLLMクライアント（Claude Code、Claude Desktopなど）から、自然言語でFreedcampのプロジェクト、タスク、ユーザー、コメントを管理できます。

特徴

  • 17個のツール：プロジェクト、タスク、ユーザー、コメント、ヘルスチェックを網羅

  • HMAC-SHA1認証 — APIシークレットはサーバーから外部へ送信されず、リクエストごとに署名されたハッシュのみが送信されます

  • 名前解決 — 数値のIDの代わりにユーザー名、メールアドレス、プロジェクト名を使用可能。サーバーがTTLベースのキャッシュを使用して自動的に解決します

  • フィールド制限 — ドット記法（id,title,comments.created_ts）を使用して必要なフィールドのみを要求し、レスポンスサイズを削減します

  • ステータスラベルのマッピング — 数値コードの代わりに"in progress"のような人間が読める文字列を受け付けます

  • レスポンスフィルタリング — 内部APIフィールドはレスポンスから自動的に削除されます

  • グレースフルシャットダウン — 終了前に実行中のリクエストを完了させます

  • リトライ + バックオフ — 429および5xxエラー時に指数バックオフでリトライします

  • ビルドステップ不要 — tsxを使用してTypeScriptを直接実行します

Related MCP server: toggl-mcp

前提条件

  • Node.js >= 18

  • API認証情報を持つFreedcampアカウント（設定 → API）

インストール

git clone https://github.com/mahrukh-n8n/freedcampMCP.git
cd freedcampMCP
npm install

設定

オプションA: .envファイル

cp .env.example .env
# Edit .env with your Freedcamp API key and secret

オプションB: Claude Code MCP設定

.envファイルは不要です。環境変数として認証情報を渡します：

claude mcp add freedcamp npx tsx /path/to/freedcampMCP/scripts/mcp-server.ts \
  -e FREEDCAMP_API_KEY=your_key \
  -e FREEDCAMP_API_SECRET=your_secret

環境変数

変数

必須

デフォルト

説明

FREEDCAMP_API_KEY

はい

—

Freedcamp APIキー

FREEDCAMP_API_SECRET

はい

—

Freedcamp APIシークレット

FREEDCAMP_API_URL

いいえ

https://freedcamp.com

ベースURL（セルフホスト用）

LOG_LEVEL

いいえ

info

ログレベル: debug, info, warn, error

REQUEST_TIMEOUT_MS

いいえ

30000

HTTPリクエストタイムアウト（ミリ秒）

CACHE_TTL_MS

いいえ

60000

名前解決キャッシュのTTL（ミリ秒）

MAX_CONCURRENT_REQUESTS

いいえ

6

最大同時APIリクエスト数

実行方法

Claude Codeで使用する場合（推奨）

claude mcp addでMCPサーバーを追加した後、会話を開始するだけです。Claudeが必要に応じて自動的にツールを呼び出します。

MCP Inspectorで使用する場合

npx @modelcontextprotocol/inspector npx tsx scripts/mcp-server.ts

ブラウザUIが開き、各ツールを呼び出してレスポンスを確認できます。

直接実行（stdio）

npx tsx scripts/mcp-server.ts

サーバーはMCP stdioトランスポートを使用してstdin/stdoutでリッスンします。ホストプロセス（Claude Code、Claude Desktop）がライフサイクルを管理します。

ツール

ヘルスチェック

ツール

説明

health.check

API認証情報と接続状態を確認する

プロジェクト

ツール

書き込み

説明

project.list

プロジェクト一覧を取得（ページネーション、ソート、フィールド制限対応）

project.get

IDまたは名前でプロジェクトを取得

project.create

はい

プロジェクトを作成（名前、説明、色、グループ、メンバー）

project.update

はい

プロジェクトフィールドを更新（部分更新）

タスク

ツール

書き込み

説明

task.list

フィルタ付きでタスク一覧を取得（担当者、ステータス、日付範囲、検索、タグ）

task.get

コメントとタグ詳細を含むタスクをIDで取得。task_urlを注入

task.create

はい

タスクを作成（ステータスラベル対応、ファイル添付）

task.update

はい

タスクフィールドを更新（部分更新、ファイル添付）

task.delete

はい

タスクを削除

task.assign

はい

タスクにユーザーを割り当て

ユーザー

ツール

書き込み

説明

user.list

ユーザー一覧を取得（プロジェクトによるフィルタリング可能）

user.get

ID、メールアドレス、または名前でユーザーを取得

user.current

認証済みユーザーのプロフィールを取得

user.create

はい

ユーザーを作成（メール、パスワード、名、OAuth）

user.update_current

はい

認証済みユーザーのプロフィールを更新

コメント

ツール

書き込み

説明

comment.add

はい

コメントを追加（item_id + app_idが必要）

comment.update

はい

コメントテキストを更新

comment.delete

はい

コメントを削除

名前解決

ほとんどのIDパラメータは、名前、メールアドレス、または数値IDを受け付けます。例：

  • project_id: "Marketing" — プロジェクトの数値IDに解決されます

  • assigned_to_id: "alice@example.com" — ユーザーの数値IDに解決されます

  • assigned_to_id: ["Alice", 42] — 混在リストも受け付けます

解決結果は設定可能なTTL（CACHE_TTL_MS）でキャッシュされます。

ステータスマッピング

タスクステータスは数値コードと文字列ラベルの両方を受け付けます：

コード

ラベル

0

not started

1

in progress

2

completed

例: status: "in progress" は status: 1 と同等です。

フィールド制限

すべてのリストおよび取得ツールは、ドット記法パスを持つfieldsパラメータを受け付けます：

fields="id,title,priority,comments.created_ts"

これによりレスポンスサイズが削減され、LLMが関連データに集中できるようになります。ネストされた配列は保持されます — [{created_ts: 1}] に対する comments.created_ts は、フラットなリストではなく [{created_ts: 1}] を返します。

アプリID定数（コメント用）

アプリ

ID

tasks

2

milestones

3

discussions

5

files

6

time

8

issue_tracker

9

認証

サーバーはHMAC-SHA1認証を使用します。すべてのリクエストにおいて：

  1. Unixタイムスタンプが生成されます

  2. ハッシュが計算されます: HMAC-SHA1(secret, apiKey + timestamp)

  3. 認証パラメータがクエリ文字列として送信されます: ?api_key=...&timestamp=...&hash=...

シークレットはネットワーク上を流れません。起動時に、サーバーは GET /api_key/check で認証情報を検証します。

エラーコード

コード

意味

PERMISSION_DENIED

APIキー/シークレットが無効、またはアクセス権限不足

NOT_FOUND

要求されたリソースまたは名前解決ターゲットが存在しない

VALIDATION_ERROR

入力パラメータが無効

CONFLICT

リソースが既に存在する

INTERNAL_ERROR

サーバーエラー、レート制限、またはネットワーク障害

開発

# Type check
npx tsc --noEmit

# Run tests
npx vitest run

# Watch mode
npx vitest

# Run server in dev mode
npm run dev

テスト

テストスイートは、モック化されたAPIレスポンスを使用してVitestで実行されます：

npx vitest run           # Single run
npx vitest               # Watch mode
npx vitest --coverage    # With coverage

プロジェクト構造

scripts/mcp-server.ts              Entry point
src/lib/freedcamp/
  api-client.ts                    HTTP client with HMAC auth, retry, filtering
  register-tools.ts                Wire all tools to the MCP registry
  auth/hmac.ts                     HMAC-SHA1 computation
  auth/hmac-validator.ts           Boot-time credential validation
  tools/
    health.ts                      health.check
    projects.ts                    project.list/get/create/update
    tasks.ts                       task.list/get/create/update/delete/assign
    users.ts                       user.list/get/current/create/update_current
    comments.ts                    comment.add/update/delete
  utils/
    name-resolver.ts               Name/email → ID resolution with caching
    response-filter.ts             Strip internal fields from API responses
    field-limiter.ts               Dot-notation field extraction
    date-utils.ts                  Date validation and formatting
    resolution-cache.ts            TTL-based LRU cache
    logger.ts                      Structured logging with verbose mode
    validation.ts                  Input validation helpers
src/modules/mcp/
  registry/tool-registry.ts        MCP tool registry
  services/create-mcp-server.ts    MCP server factory
  services/stdio-transport.ts      Stdio transport
  types.ts                         MCP result types
  utils/serialize.ts               Result envelope helpers (dataResult, commitResult, etc.)

ライセンス

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers