Simple Stickers API & MCP Dokumentation

🔑

Authentifizierung

Sowohl die REST API als auch der MCP Server verwenden Bearer Token-Authentifizierung über einen API-Schlüssel.

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

🔧 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"}'

Parameter	Typ	Erforderlich	Beschreibung
`project_id`	string (UUID)	Ja
`status`	string	Nein	Nach Statuswert filtern (siehe Enum unten)

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`

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

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 oder ungültig
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

delete_task

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

💻

Claude Code Einrichtung

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

🌐 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 11 verfügbaren Tools. Wenn der Server als getrennt angezeigt wird, klicken Sie auf Reconnect.

🖥️

Claude Desktop Einrichtung

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"

# Handshake (keine Authentifizierung erforderlich)
curl -s -X POST $BASE \
  -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}'