Freedcamp MCP Server
Freedcamp MCP-Server
Ein Model Context Protocol-Server, der die Freedcamp REST-API kapselt. Er ermöglicht es jedem MCP-kompatiblen LLM-Client (Claude Code, Claude Desktop usw.), Freedcamp-Projekte, Aufgaben, Benutzer und Kommentare mittels natürlicher Sprache zu verwalten.
Funktionen
17 Tools für Projekte, Aufgaben, Benutzer, Kommentare und Gesundheitsprüfungen
HMAC-SHA1-Authentifizierung — das API-Geheimnis verlässt niemals den Server; pro Anfrage wird nur ein signierter Hash gesendet
Namensauflösung — übergeben Sie Benutzernamen, E-Mails oder Projektnamen anstelle von rohen numerischen IDs; der Server löst diese automatisch mit TTL-basiertem Caching auf
Feldbegrenzung — fordern Sie nur die benötigten Felder mit Punktnotation (
id,title,comments.created_ts) an, um die Antwortgröße zu reduzierenStatus-Label-Mapping — akzeptiert menschenlesbare Zeichenfolgen wie
"in progress"anstelle von numerischen CodesAntwortfilterung — interne API-Felder werden automatisch aus den Antworten entfernt
Graceful Shutdown — laufende Anfragen werden vor dem Beenden abgeschlossen
Wiederholung + Backoff — Wiederholungsversuche bei 429 und 5xx mit exponentiellem Backoff
Kein Build-Schritt — führt TypeScript direkt über tsx aus
Related MCP server: MCP Redmine
Voraussetzungen
Node.js >= 18
Ein Freedcamp-Konto mit API-Anmeldedaten (Einstellungen → API)
Installation
git clone https://github.com/mahrukh-n8n/freedcampMCP.git
cd freedcampMCP
npm installKonfiguration
Option A: .env-Datei
cp .env.example .env
# Edit .env with your Freedcamp API key and secretOption B: Claude Code MCP-Einstellungen
Keine .env-Datei erforderlich — übergeben Sie Anmeldedaten als Umgebungsvariablen:
claude mcp add freedcamp npx tsx /path/to/freedcampMCP/scripts/mcp-server.ts \
-e FREEDCAMP_API_KEY=your_key \
-e FREEDCAMP_API_SECRET=your_secretUmgebungsvariablen
Variable | Erforderlich | Standard | Beschreibung |
| Ja | — | Freedcamp API-Schlüssel |
| Ja | — | Freedcamp API-Geheimnis |
| Nein |
| Basis-URL (für selbst gehostete Instanzen) |
| Nein |
| Log-Level: debug, info, warn, error |
| Nein |
| HTTP-Anfrage-Timeout (ms) |
| Nein |
| TTL für Namensauflösungs-Cache (ms) |
| Nein |
| Maximale gleichzeitige API-Anfragen |
Ausführung
Mit Claude Code (empfohlen)
Nachdem Sie den MCP-Server mit claude mcp add hinzugefügt haben, starten Sie einfach eine Konversation. Claude ruft die Tools bei Bedarf automatisch auf.
Mit MCP Inspector
npx @modelcontextprotocol/inspector npx tsx scripts/mcp-server.tsÖffnet eine Browser-Benutzeroberfläche, in der Sie jedes Tool aufrufen und Antworten untersuchen können.
Direkt (stdio)
npx tsx scripts/mcp-server.tsDer Server lauscht auf stdin/stdout unter Verwendung des MCP-stdio-Transports. Der Host-Prozess (Claude Code, Claude Desktop) verwaltet seinen Lebenszyklus.
Tools
Gesundheit
Tool | Beschreibung |
| Überprüft API-Anmeldedaten und Verbindungsstatus |
Projekte
Tool | Schreiben | Beschreibung |
| Listet Projekte auf (paginiert, sortierbar, feldbegrenzbar) | |
| Ruft Projekt per ID oder Name ab | |
| Ja | Erstellt ein Projekt (Name, Beschreibung, Farbe, Gruppe, Mitglieder) |
| Ja | Aktualisiert Projektfelder (partielle Aktualisierung) |
Aufgaben
Tool | Schreiben | Beschreibung |
| Listet Aufgaben mit Filtern auf (Bearbeiter, Status, Datumsbereich, Suche, Tags) | |
| Ruft Aufgabe per ID mit Kommentaren und Tag-Details ab; fügt | |
| Ja | Erstellt eine Aufgabe (Status-Labels akzeptiert, Dateianhänge) |
| Ja | Aktualisiert Aufgabenfelder (partielle Aktualisierung, Dateianhänge) |
| Ja | Löscht eine Aufgabe |
| Ja | Weist Benutzer einer Aufgabe zu |
Benutzer
Tool | Schreiben | Beschreibung |
| Listet Benutzer auf (optional nach Projekt gefiltert) | |
| Ruft Benutzer per ID, E-Mail oder Name ab | |
| Ruft das Profil des authentifizierten Benutzers ab | |
| Ja | Erstellt einen Benutzer (E-Mail, Passwort, Vorname, OAuth) |
| Ja | Aktualisiert das Profil des authentifizierten Benutzers |
Kommentare
Tool | Schreiben | Beschreibung |
| Ja | Fügt einen Kommentar hinzu (erfordert item_id + app_id) |
| Ja | Aktualisiert den Kommentartext |
| Ja | Löscht einen Kommentar |
Namensauflösung
Die meisten ID-Parameter akzeptieren Namen, E-Mails oder numerische IDs. Beispiele:
project_id: "Marketing"— wird in die numerische ID des Projekts aufgelöstassigned_to_id: "alice@example.com"— wird in die numerische ID des Benutzers aufgelöstassigned_to_id: ["Alice", 42]— gemischte Listen werden akzeptiert
Auflösungsergebnisse werden mit einer konfigurierbaren TTL (CACHE_TTL_MS) zwischengespeichert.
Status-Mapping
Der Aufgabenstatus akzeptiert sowohl numerische Codes als auch String-Labels:
Code | Label |
0 | not started |
1 | in progress |
2 | completed |
Beispiel: status: "in progress" entspricht status: 1.
Feldbegrenzung
Alle Listen- und Abruf-Tools akzeptieren einen fields-Parameter mit Pfaden in Punktnotation:
fields="id,title,priority,comments.created_ts"Dies reduziert die Antwortgröße und fokussiert das LLM auf relevante Daten. Verschachtelte Arrays bleiben erhalten — comments.created_ts bei [{created_ts: 1}] ergibt [{created_ts: 1}], keine flache Liste.
App-ID-Konstanten (für Kommentare)
App | ID |
tasks | 2 |
milestones | 3 |
discussions | 5 |
files | 6 |
time | 8 |
issue_tracker | 9 |
Authentifizierung
Der Server verwendet HMAC-SHA1-Authentifizierung. Bei jeder Anfrage:
Ein Unix-Zeitstempel wird generiert
Ein Hash wird berechnet:
HMAC-SHA1(secret, apiKey + timestamp)Auth-Parameter werden als Query-String gesendet:
?api_key=...×tamp=...&hash=...
Das Geheimnis wird niemals übertragen. Beim Start validiert der Server die Anmeldedaten mit GET /api_key/check.
Fehlercodes
Code | Bedeutung |
| Ungültiger API-Schlüssel/Geheimnis oder unzureichender Zugriff |
| Angeforderte Ressource oder Ziel der Namensauflösung existiert nicht |
| Ungültige Eingabeparameter |
| Ressource existiert bereits |
| Serverfehler, Ratenbegrenzung oder Netzwerkfehler |
Entwicklung
# Type check
npx tsc --noEmit
# Run tests
npx vitest run
# Watch mode
npx vitest
# Run server in dev mode
npm run devTesten
Die Test-Suite verwendet Vitest mit gemockten API-Antworten:
npx vitest run # Single run
npx vitest # Watch mode
npx vitest --coverage # With coverageProjektstruktur
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.)Lizenz
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Manage projects, tasks, time tracking, and team collaboration through natural language.
Read teams, spaces, lists and tasks; create, update and comment on tasks and track time.
Read projects, tasks, comments, people and time entries; create tasks and comments in ProofHub.
Read and edit your Tasks boards: create and update tasks, comment, and track time.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables to manage Toggl time entries, projects, tasks, and timers through natural language commands.MIT
- FlicenseNot gradedqualityCmaintenanceEnables to manage Redmine projects, issues, users, and time entries through natural language using the Redmine REST API.-
- AlicenseNot gradedqualityDmaintenanceEnables managing CompanyCam projects, photos, tags, comments, and users through natural language, using the CompanyCam API.MIT
- AlicenseAqualityFmaintenanceEnables managing amoCRM data through natural language, including leads, contacts, companies, pipelines, tasks, notes, search, events, and unsorted leads.19124 npmMIT