Simple Stickers API & MCP Dokumentation

🔑

Authentifizierung

Sowohl die REST API als auch der MCP Server verwenden Bearer Token-Authentifizierung über einen API-Schlüssel. Claude.ai (Web, Desktop-App, Mobil) meldet sich am MCP Server stattdessen per OAuth an — Sie müssen keinen Schlüssel generieren oder kopieren, siehe Mit Claude.ai verbinden.

Token-Typ	Gültigkeitsdauer	Wie man ihn erhält
`ss_<40 hex chars>` — API-Schlüssel	Langlebig — gültig bis widerrufen	Generieren in Kontoeinstellungen → API-Reiter
`ss_…` — per OAuth ausgestellter Schlüssel	Langlebig — gültig bis widerrufen	Wird beim Verbinden von Claude.ai automatisch erstellt (in der Schlüsselliste mit der Quelle „Verbundene App“)

🔧 API-Schlüssel generieren

1 Öffnen Sie Simple Stickers und klicken Sie auf Ihren Avatar oben rechts
2 Gehen Sie zu Kontoeinstellungen → API Reiter
3 Klicken Sie auf API-Schlüssel generieren, geben Sie optional einen Namen an
4
Kopieren Sie den Schlüssel sofort — er wird nur einmal angezeigt
Der Schlüssel beginnt mit ss_ gefolgt von 40 Hexadezimalzeichen.

📤 Token verwenden

Übergeben Sie den Token bei jeder Anfrage als Bearer Authorization Header:

Authorization: Bearer ss_a1b2c3d4e5f6...

API-Schlüssel sind auf den Benutzer beschränkt, der sie erstellt hat. Alle Datenvorgänge geben nur die Daten dieses Benutzers zurück.

📡

REST API

🌐 Endpunkt

POST https://www.simplestickers.app/api/agent
Content-Type: application/json
Authorization: Bearer <token>

📨 Anfrage-Body

Alle Aktionen teilen den gleichen JSON Umschlag:

{
  "action": "<action_name>",
  "<param>": "<value>"
}

📬 Antworten

200 OK Erfolg — JSON-Daten im Body
4xx / 5xx Fehler — {"error": "message"}

📁

Projekte

list_projects

Gibt alle Projekte des authentifizierten Benutzers zurück.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_projects"}'

Antwort: Array von {"id","name","created_at"} Objekten.

find_project

Suche mit Teiltreffer unabhängig von Groß-/Kleinschreibung. Gibt ein Array von übereinstimmenden Projekten zurück.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"find_project","name":"My Work"}'

Parameter	Typ	Erforderlich
`name`	string	Ja

create_project

Erstellt ein neues Projekt. Gibt das erstellte Projektobjekt zurück.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"create_project","name":"Q3 Campaign"}'

Parameter	Typ	Erforderlich
`name`	string	Ja

rename_project

Benennt ein vorhandenes Projekt um.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"rename_project","project_id":"<uuid>","name":"New Name"}'

Parameter	Typ	Erforderlich
`project_id`	string (UUID)	Ja
`name`	string	Ja

delete_project

Löscht ein Projekt und alle seine Aufgaben (kaskadierend). Gibt {"success":true} zurück.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"delete_project","project_id":"<uuid>"}'

⚠️ Nicht umkehrbar. Alle Aufgaben im Projekt werden dauerhaft gelöscht.

📝

Aufgaben

list_tasks

Gibt Aufgaben in einem Projekt zurück, geordnet nach Position. Optional gefiltert nach Status.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_tasks","project_id":"<uuid>"}'

# Nach Status filtern:
-d '{"action":"list_tasks","project_id":"<uuid>","status":"in_progress"}'

# Kompaktmodus ohne vollständige Notizen:
-d '{"action":"list_tasks","project_id":"<uuid>","include_notes":false}'

Parameter	Typ	Erforderlich	Beschreibung
`project_id`	string (UUID)	Ja
`status`	string	Nein	Nach Statuswert filtern (siehe Enum unten)
`include_notes`	boolean	Nein	Bei `false` werden statt der vollständigen Notizen `notes_preview` (erste Zeile) und `notes_chars` zurückgegeben — deutlich kleinere Antwort, ideal für Orchestrierungs-Loops

get_task

Gibt eine einzelne Aufgabe nach ID zurück, einschließlich ihrer project_id.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"get_task","task_id":"<uuid>"}'

create_task

Erstellt eine neue Aufgabe in einem Projekt. Gibt das erstellte Aufgabeobjekt zurück.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_task",
    "project_id": "<uuid>",
    "text": "Write unit tests",
    "priority": true,
    "color": "yellow",
    "deadline": "2026-06-30",
    "notes": "## Context\n\n- Cover happy path\n- Cover edge cases"
  }'

Parameter	Typ	Erforderlich	Standard
`project_id`	string (UUID)	Ja
`text`	string	Ja
`status`	string	Nein	`backlog`
`notes`	string (Markdown)	Nein	`null`
`priority`	boolean	Nein	`false`
`color`	string \| null	Nein	`null` (weiß)
`deadline`	string (YYYY-MM-DD) \| null	Nein	`null`
`position`	number	Nein	Ende der Spalte (`max + 1000`)

update_task

Aktualisiert ein oder mehrere Felder einer bestehenden Aufgabe. Mindestens ein optionales Feld muss angegeben werden.

# Aufgabe zu in_progress verschieben:
curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<uuid>","status":"in_progress"}'

# Mehrere Felder auf einmal aktualisieren:
-d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'

Parameter	Typ	Erforderlich
`task_id`	string (UUID)	Ja
`text`	string	Nein
`status`	string	Nein
`notes`	string (Markdown) \| null	Nein
`priority`	boolean	Nein
`color`	string \| null	Nein
`deadline`	string (YYYY-MM-DD) \| null	Nein
`position`	number	Nein

append_to_notes

Hängt Text an das Ende der Notizen einer Aufgabe an, ohne die bestehenden Notizen erneut zu senden. Der neue Text wird durch eine Leerzeile getrennt (sind die Notizen leer, wird nur der neue Text gespeichert). Der Vorgang ist atomar, gleichzeitige Anhänge überschreiben sich also nicht. Gibt die aktualisierte Aufgabe zurück.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"append_to_notes","task_id":"<uuid>","text":"## Testergebnis\n\n- Alles bestanden"}'

Parameter	Typ	Erforderlich
`task_id`	string (UUID)	Ja
`text`	string (Markdown)	Ja

delete_task

Löscht eine Aufgabe dauerhaft. Gibt {"success":true} zurück.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"delete_task","task_id":"<uuid>"}'

📋 Enum-Werte

status

backlog
in_progress
review
testing
done

color

yellow
green
blue
null (weiß)

deadline

YYYY-MM-DD string, oder null zum Löschen.

priority

true = hohe Priorität
false = normal

📄

Aufgabennotizen (Markdown)

Aufgabennotizen werden als plain Markdown Strings gespeichert und übertragen. Das Frontend rendert sie über react-markdown. Schreiben und lesen Sie immer Markdown — kein HTML.

Syntax	Ergebnis
`text`	Fett
`text`	Kursiv
`~~text~~`	~~Durchgestrichen~~
`## Heading`	H2 Überschrift
`### Heading`	H3 Überschrift
`- item`	Aufzählungsliste
`1. item`	Nummerierte Liste
`code`	Inline Code
```\ncode\n```	Codeblock
`> text`	Blockzitat
`[text](url)`	Hyperlink

📋 Beispiel-Notiz in create_task

"notes": "## Task overview\n\n- Requirement 1\n- Requirement 2\n\n**Important:** deadline is Friday\n\n[Design brief](https://example.com/brief)"

Ältere Notizen: Notizen, die vor der Markdown-Migration gespeichert wurden, können HTML enthalten. Das Frontend konvertiert sie automatisch bei der Anzeige. Beim Lesen über die API können alte Notizen HTML-Strings zurückgeben — schreiben Sie immer Markdown, seien Sie beim Lesen tolerant.

⚙️

Einstellungen

get_column_settings

Gibt die Kanban-Spalten-Sichtbarkeitseinstellungen des Benutzers zurück.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"get_column_settings"}'

Beispielantwort:

{
  "columns": {
    "backlog":     true,
    "in_progress": true,
    "review":      false,
    "testing":     false,
    "done":        true
  }
}

columns ist null, wenn der Benutzer die Spaltensichtbarkeit nicht angepasst hat (alle Standard gelten).

❌

Fehlerreferenz

HTTP-Status	`error` Wert	Bedeutung
401	`Unauthorized`	Token fehlt, ist ungültig oder widerrufen. Der MCP Server liefert zusätzlich einen `WWW-Authenticate`-Header mit Verweis auf die OAuth-Metadaten.
400	`Missing <param>`	Erforderlicher Parameter nicht angegeben
400	`Unknown action`	Aktionsname nicht erkannt
403	`Key management requires JWT authentication`	Versuch, Schlüssel mit API-Schlüssel-Token zu verwalten
500	varies	Unerwarteter Serverfehler

🤖

MCP-Integration

Was ist MCP?

MCP (Model Context Protocol) ist ein Standard, der es KI-Clients (Claude Code, Claude Desktop, Cursor…) ermöglicht, sich mit externen Tools zu verbinden. Anders als die REST API beschreibt sich der MCP Server selbst — der Client fragt, welche Tools existieren, und ruft sie dann direkt auf, ohne URLs oder Anfrage-Formate kennen zu müssen.

✅ MCP verwenden, wenn…

• Sie möchten, dass Claude Ihre Aufgaben dialogisch verwaltet
• Sie benötigen, dass die KI verfügbare Operationen selbst erkennt
• Sie eine schlüsselfertige Integration mit Claude Code / Claude Desktop bevorzugen
• Sie natürliche Sprache anstelle von curl-Befehlen verwenden möchten

📡 REST API verwenden, wenn…

• Sie Ihre eigenen Automatisierungsskripte oder CI-Pipelines erstellen
• Sie granulare Kontrolle über HTTP-Anfragen benötigen
• Sie mit Systemen integrieren, die MCP nicht unterstützen
• Sie Antworten programmgesteuert verarbeiten möchten

🛠️ Verfügbare MCP-Tools

list_projects

find_project

create_project

rename_project

delete_project

get_column_settings

list_tasks

get_task

create_task

update_task

append_to_notes

delete_task

MCP-Endpunkt: https://www.simplestickers.app/api/mcp (Streamable HTTP Transport, JSON-RPC 2.0)

🔌 So verbinden Sie sich

• Claude.ai — Web, Desktop-App, Mobil: benutzerdefinierter Connector mit OAuth-Anmeldung, ohne API-Schlüssel — Anleitung
• Claude Code: Konfiguration mit API-Schlüssel im Header oder OAuth-Anmeldung — Anleitung
• n8n und andere Tools: HTTP-MCP-Client mit dem Header Authorization: Bearer ss_… (Schlüssel aus Kontoeinstellungen → API)

☁️

Mit Claude.ai verbinden

Fügen Sie Simple Stickers in Claude als benutzerdefinierten Connector hinzu. Sie melden sich mit Ihrem Simple Stickers-Konto an und erlauben den Zugriff — ein API-Schlüssel muss weder generiert noch irgendwo eingefügt werden. Der Connector funktioniert dann in Claude im Web, in der Desktop-App und auf dem Handy.

🔗 Vorgehen

1 Öffnen Sie in Claude Settings → Connectors und klicken Sie auf Add custom connector
2
Geben Sie einen beliebigen Namen (z. B. Simple Stickers) und die Server-URL ein:
https://www.simplestickers.app/api/mcp
3 Klicken Sie auf Connect — eine Simple Stickers-Seite öffnet sich
4 Melden Sie sich an (per E-Mail oder Google) und klicken Sie auf Erlauben. Sie kehren zu Claude zurück und der Connector ist verbunden.

✅ Wie geht es weiter

• Der Connector wird mit der Claude Desktop-App und dem Handy synchronisiert — Sie richten ihn nur einmal ein
• Im Gespräch genügt z. B. „Welche Aufgaben habe ich im Projekt Website?“
• Claude hat denselben Zugriff wie Sie: Es kann Ihre Projekte und Aufgaben sehen, erstellen, bearbeiten und löschen

🔌 Trennen

• Öffnen Sie in Simple Stickers Kontoeinstellungen → API-Reiter
• Widerrufen Sie den Schlüssel mit der Quelle Verbundene App (Name „Claude“) über die Schaltfläche Widerrufen
• Ab dann hat Claude keinen Zugriff mehr auf Ihr Konto; zum erneuten Verbinden klicken Sie in Claude einfach wieder auf Connect

In den Claude-Plänen Team / Enterprise können nur Organisationsinhaber benutzerdefinierte Connectoren hinzufügen; die übrigen Mitglieder verbinden sich dann nur mit ihrem eigenen Konto.

💻

Claude Code Einrichtung

Claude Code unterstützt HTTP MCP-Server nativ — kein Proxy erforderlich. Konfigurieren Sie einmal global oder pro Projekt.

🔐 Am einfachsten: Anmeldung per OAuth (ohne API-Schlüssel)

Fügen Sie den Server ohne Header hinzu und melden Sie sich dann mit /mcp → simplestickers → Authenticate an. Es öffnet sich ein Browser mit derselben Zustimmungsseite wie bei Claude.ai.

claude mcp add --transport http simplestickers https://www.simplestickers.app/api/mcp

Für Skripte und geteilte Konfigurationen können Sie weiterhin einen API-Schlüssel im Header verwenden — siehe unten.

🌐 Globale Konfiguration — ~/.claude/mcp.json

Gilt für alle Claude Code Sitzungen auf Ihrem Computer:

{
  "mcpServers": {
    "simplestickers": {
      "type": "http",
      "url": "https://www.simplestickers.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ss_your_api_key_here"
      }
    }
  }
}

📁 Pro-Projekt-Konfiguration — .mcp.json im Projektroot

Gleiches Format wie globale Konfiguration — gilt nur beim Arbeiten in diesem Verzeichnis:

{
  "mcpServers": {
    "simplestickers": {
      "type": "http",
      "url": "https://www.simplestickers.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ss_your_api_key_here"
      }
    }
  }
}

✅ Verbindung prüfen

Nach dem Speichern der Konfiguration öffnen Sie Claude Code und geben Sie ein:

/mcp

Sie sollten simplestickers aufgelistet sehen mit allen 12 verfügbaren Tools. Wenn der Server als getrennt angezeigt wird, klicken Sie auf Reconnect.

🖥️

Claude Desktop Einrichtung

Empfohlen: Am einfachsten fügen Sie Simple Stickers als Connector in Claude.ai hinzu — er erscheint automatisch auch in Claude Desktop und auf dem Handy, ohne Konfigurationsdateien und ohne API-Schlüssel. Siehe Mit Claude.ai verbinden. Die manuelle Konfiguration unten ist eine Alternative für die lokale Einrichtung mit API-Schlüssel.

Wichtig: Claude Desktop unterstützt HTTP MCP Transport nicht direkt — es nutzt nur stdio Transport. Verwenden Sie mcp-remote als Proxy. Das -y Flag genehmigt automatisch die npm-Installation ohne interaktive Eingabeaufforderungen.

🍎 macOS

Konfigurationsdatei: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "simplestickers": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.simplestickers.app/api/mcp",
        "--header",
        "Authorization: Bearer ss_your_api_key_here"
      ]
    }
  }
}

🪟 Windows

Konfigurationsdatei: %APPDATA%\Claude\claude_desktop_config.json

(normalerweise C:\Users\<name>\AppData\Roaming\Claude\claude_desktop_config.json)

Unter Windows startet Claude Desktop Prozesse ohne Shell-Kontext, daher muss npx in cmd /c eingewickelt werden:

{
  "mcpServers": {
    "simplestickers": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://www.simplestickers.app/api/mcp",
        "--header",
        "Authorization: Bearer ss_your_api_key_here"
      ]
    }
  }
}

Nach dem Bearbeiten der Konfiguration starten Sie Claude Desktop neu. Sie sollten die Simple Stickers Tools in der Tool-Liste in einer Unterhaltung sehen.

💡

Schnellbeispiele

📡 Kompletter REST-Workflow — Projekt finden → Aufgabe erstellen → Status aktualisieren

BASE="https://www.simplestickers.app/api/agent"
TOKEN="ss_your_api_key_here"

# 1. Projekt finden
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"find_project","name":"My Work"}'

# 2. Aufgabe erstellen (project_id aus Schritt 1 verwenden)
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_task",
    "project_id": "<project-uuid>",
    "text": "Write unit tests",
    "priority": true,
    "color": "yellow"
  }'

# 3. Aufgabe zu in_progress verschieben (Task ID aus Schritt 2 verwenden)
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update_task",
    "task_id": "<task-uuid>",
    "status": "in_progress"
  }'

# 4. Als erledigt markieren
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<task-uuid>","status":"done"}'

🤖 MCP-Workflow in Claude Code

Sobald der MCP-Server konfiguriert ist, können Sie natürlich mit Claude sprechen:

Sie: Find my "Website Redesign" project and list all tasks that are in_progress

Sie: Create a high-priority task "Fix mobile navigation" with a deadline of 2026-06-30 and add notes with a checklist

Sie: Move all tasks named "Deploy *" to done status

Claude nutzt die MCP-Tools automatisch basierend auf Ihren natürlichsprachlichen Anweisungen.

🔬 MCP-Server direkt mit curl testen

BASE="https://www.simplestickers.app/api/mcp"
TOKEN="ss_your_api_key_here"

# Ohne Token → HTTP 401 + WWW-Authenticate (OAuth-Discovery)
curl -s -i -X POST $BASE -H "Content-Type: application/json" -d '{}'

# Handshake
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}},"id":1}'

# Tools auflisten
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

# Tool aufrufen
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_projects","arguments":{}},"id":3}'