Backlog Remote MCP Server

Ein Remote-MCP-Server (Model Context Protocol) für Backlog. Auf Cloudflare Workers oder AWS bereitstellbar.

Englisch | 日本語

Funktionen

• Multi-Space – mehrere Backlog-Spaces über einen Server bedienen

• Read-only-Schutz – einen geteilten Space als readOnly markieren, um jeden Schreib-API-Aufruf abzulehnen

• OAuth 2.1 + PKCE – unterstützt Dynamic Client Registration (DCR), sodass sich MCP-Clients direkt verbinden können

• E-Mail-Allowlist – schränkt ein, wer den Server verwenden darf

• Zwei Laufzeitumgebungen – dieselbe Geschäftslogik läuft auf Cloudflare oder AWS

Related MCP server: backlog-mcp-server

Auswahl einer Bereitstellung

Die Tools und ihr Verhalten sind auf beiden Plattformen identisch.

Geschätzte Kosten

Hinweis Hierbei handelt es sich nur um Referenzwerte. Die tatsächlichen Kosten variieren je nach Region, Nutzung und Preisänderungen. Für eine echte Schätzung verwenden Sie die offiziellen Rechner.

• Cloudflare Zero Trust-Preise

• Cloudflare Workers-Preise

• AWS-Preisrechner

Annahmen

Privater Gebrauch oder ein kleines Team.

Fixkosten (auch bei Nicht genutzt werden)

Auf AWS besteht die Fixkosten ist im Wesentlichen nur das Secrets Manager, das pro Secret und Monat berechnet wird, unabhängig davon, ob es verwendet wird. Cloudflare hat keine Festkosten, weil Workers Secrets kostenlos sind.

Was abgerechnet wird

Bei der angenommenen Menge (~3.000 Anfragen/Monat) ** bleiben beide innerhalb der Source Freikontingente**. Das API Gateway HTTP API hat kein dauerhaftes kostenloses Kontingent, daher fallen bei AWS geringe Kosten proportional zur Anfragenzahl an (etwa $1 pro Million Anfragen).

Wichtige Grenzwerte

Cloudflare – die 50-Nutzer-Grenze bei Zero Trust

Zero Trust (Access) ist für bis zu 50 Benutzer kostenlos. Pripped danach wechseln Sie zu einem kostenpflichtigen Plan mit Abrechnung pro Benutzer und Monat. Das ist die Kostenposition, die mit dem number of growth steigt.

Cloudflare – Grenzen des Workers Free Plan

Dieses Projekt verwendet SQLite-basierten Durable Objects, die im Workers Free Plan verfügbar sind. Der Free Plan begrenzt die Anzahl der täglichen Anfragen und andere Nutzung; wird eine Grenze überschritten, upon Fehler zurückgegeben. Für langfristige Nutzung z deem Workers Paid Plan in Betracht (auch ab 5 $/Monat).

AWS – Das Lambda Free Tier ist dauerhaft

Lambda besitzt ein dauerhaftes Free Tier von 1M Anfragen und 400.000 GB-Sekunden pro Monat. API Gateway und Secrets Manager besitzen kein dauerhaftes Free Tier.

AWS – CloudWatch Logs

Logs werden nach Aufnahmevolumen abgerechnet. Diese Vorlage verwaltet die Aufbewahrung explizit über LogRetentionDays (Standard 30), sodass Logs nicht unbegrenzt wachsen.

Zusammenfassung

** Für kleine Teams ist Cloudflare einfacher und hat keine Fixkosten.****AWS trägt die Fixkosten für Secrets Manager, lohnt sich aber, wenn Sie die Bereitstellung in eine bestehende AWS-Landschaft integrieren or Zugriffe über IAM steuern möchten.

Einrichtung

0. Voraussetzungen

Node.js 20 oder höher.

git clone <this-repo>
cd backlog-remote-mcp-server
npm install

Weitere Tools hängen vom Programmziel ab:

Reihenfolge

1. Backlog-API-Schlüssel und Space-Konfiguration – einteilend für beide Plattformen

2. Wählen Sie einein Gateway

   • Google Bereit

   • Microsoft Entra ID

3. Wählen Sie ein Auf einem-Standort

   • Cloudflare Workers

   • AWS

Wenn etwas schiefgeht

Die Fehlerbehebungssh-Verantwortenection ist am Ende eines Staubt Ein ges.

• Cloudflare

• AWS

Architektur

MCP client (Claude, Kiro, Cursor, ...)
    ↓ Streamable HTTP + OAuth
Runtime (Cloudflare Workers or AWS Lambda)
    ↓ Upstream IdP (Cloudflare Access or Amazon Cognito)
    ↓ Email allowlist check
    ↓ Backlog API key routing
Backlog space A / B / C ...

Verzeichnisstruktur

Die Geschäftslogik ist von der Laufzeit-Verknüpfungen getrennt.

src/
  core/                    Runtime-independent
    backlog-client.ts      Backlog API client (including the readOnly guard)
    tools/                 40 MCP tools
    create-server.ts       MCP server assembly and authorization
  platforms/
    cloudflare/            Cloudflare Workers wiring
    aws/                   AWS Lambda wiring
infra/
  aws/                     SAM template and parameters

src/core hängt nur von @modelcontextprotocol/sdk und zod ab und referenziert keine laufzeitspezifische API. Eine weitere Plattform hinzuzufügen bedeutet, einen Adapter unter src/platforms/ anzulegen und dieselben Tool-Implementierungen gemeinschaftlich zu nutzen.

Verbindung von MCP-Clients

Claude Desktop / Kiro / Cursor (über mcp-remote-Proxy)

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<MCP_HOSTNAME>/mcp"
      ]
    }
  }
}

Bei der ersten Verbindung wird ein Browserfenster zur Authentifizierung geöffnet.

MCP Inspector (zum Testen)

npx @modelcontextprotocol/inspector@latest

Geben Sie https://<MCP_HOSTNAME>/mcp in den Inspector ein und schließen Sie den OAuth-Ablauf über OAuth Settings ab.

Verwendung

Einen Space angeben

Alle Tools akzeptieren einen optionalen space-Parameter:

# Use default space
"Show me the issues for PROJECT-KEY"

# Specify a particular space
"List projects in the PERSONAL space"
→ space: "PERSONAL"

Beispiele

# List configured spaces
"What Backlog spaces are available?" → list_spaces

# List projects
"Show COMPANY_A projects" → get_project_list(space: "COMPANY_A")

# Create an issue
"Create a new bug issue in PROJECT-KEY" → add_issue(...)

# List pull requests
"Show open PRs in repo-name" → get_pull_requests(...)

Unter dem Menüpunkt

add_* , update_* und delete_* sind Schreiboperationen. Aufrufe für einen Space mit readOnly: true werden abgelehnt, noch sie die Backlog-API erreichen. Verwenden Sie list_spaces, um den readOnly-Status jedes Spaces zu sehen.

Sicherheit

• Authentifizierung: Cloudflare Access → Google / Microsoft Entra ID. Der Office- undeden-Ablauf ist completely managed da Cloudflare

• Autorisierung: ALLOWED_EMAILS stellt eine anwendungsweite E-Mail-Allowlist bereit

• Doppelte Absicherung: Access Policy (Cloudflare) + In-App-Allowlist (Worker)

• API-Schlüssel-Schutz: Backlog-API-Schlüssel liegen in Cloudflare Secrets und werden niemals an Clients weitergegeben

• unmittelbare Phonenunten: OAuth-Ablauf ist mit PKCE (S256) und CSRF-Tokens geschützt

• MMetadata of behaviors: Dynamic Client Registration ist offen für alle, daher wird die Autorisierung durch einem Zustimmungsbildschirm abgesichert, der den Client und sein Redirect-Ziel benennt und eine durch CSRF geschützte Zustimmung erfordert. Zustimmungen werden auf Basis von client_id + redirect_uri gespeichert, sodass eine neue Registrierung mitte anderem redirect_uri keine frühere Zustimmung erben kann

• Schreibschritt: Spaces mit readOnly: true lehnen jeden Nicht-GET-Aufruf ab. Die Prüfung ist in der API-Aufrufsschicht von src/core/backlog-client.ts eingebaut und hängt nicht von einer einzelnen Tool-Implementierung ab

• Konfig globale: Alle umgebungspezifischen Werte sind in .dev.vars (untracked). Das Repository entält nur Platzhalter

Sicherheitshinweise

• ALLOWED_EMAILS ist die effektive Autorisierungsgrenze für diesen Server. Es gibt keine Access-Anwendung auf Zonenebene vor dem Worker.

• npm run deploy überzeugt productionsecrets mit den Values from zu übersetzer. Wenn lokal und in production andere Werte needed, verwenden Sie deploy:no-secrets für den Routinely Deployment and setzen Secrets explizit via secrets:push.

• Ein Backlog-API-Schlüssel enthält die volle Berechtigung seines Besitzers. For Space, die keine Schreibvorgänge brauchen, you ein Lesen oder Schlüssel und setzen Sie readOnly: true.

Lokale Entwicklung

Lokal wird die Cloudflare-Workers-Build (wrangler dev) verwendet. Weil die Geschäftslogik in src/core liegt, gilt das, was Sie hier the testing. wenn auch für das AWS-Deployment.

cp .dev.vars.example .dev.vars   # fill in your values
npm run dev
# Server starts at http://localhost:8788/mcp

wrangler dev emuliert KV and Durable Objects locally, es berührt also nie Cloudflare-Ressourcen.

Einrichtung prüfen

Führen Sie die komplette OAuth- und Tool-Call-Prüfung in einem einzigen Befehl aus:

npm run check:local

Er führt Folgendes aus und öffnet dabei einen Browser, damits you sich mit Login anmelden können:

1. Abrufen der Metadaten des Authorization Servers

2. Dynamische Client-Registrierung

3. Genehmigung im Browser → IdP-Anmeldung

4. Token-Austausch mit PKCE

5. initialize / tools/list

6. Aufruf von get_space und Anzeigen der echten Antwort von Backlog

Wenn tools/list nur access_denied zurückgibt, ist die E-Mail-Adresse, mit der Sie sich angemeldet haben, nicht in der Zulassungsliste.

Es funktioniert auch gegen einen bereitgestellten Endpunkt:

npm run check:local -- --base https://your-deployed-host

Ausführen über HTTPS

Verwenden Sie dies, wenn der IdP eine http://-Redirect-URL nicht akzeptiert.

npm run dev:https
# Server starts at https://localhost:8788/mcp (self-signed certificate)

Typprüfung und Tests

Die Typen sind pro Plattform aufgeteilt, sodass die missbräuchliche Verwendung eines Workers-Globals im AWS-Code (oder umgekehrt) ein Typfehler ist.

npm run type-check   # both tsconfig.cloudflare.json and tsconfig.aws.json
npm test             # runs all suites below

Keiner davon greift auf externe Dienste zu — DynamoDB und der vorgelagerte IdP sind gestubbt.

Konfigurationsdateien

Siehe die Deployment-Anleitungen, um zu erfahren, wie Sie sie ausfüllen.

Lizenz

MIT