chore: Add n8n Claude Code plugin with setup-mcps skill (#27589)

2026-09-21 12:51:16 +08:00 · 2026-03-26 15:11:30 +00:00
parent ef506be259
commit 174aece228
6 changed files with 169 additions and 8 deletions
@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "linear": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
-    }
-  }
-}
@@ -0,0 +1,12 @@
+{
+  "name": "n8n",
+  "owner": {
+    "name": "n8n"
+  },
+  "plugins": [
+    {
+      "name": "n8n",
+      "source": "./"
+    }
+  ]
+}
@@ -0,0 +1,4 @@
+{
+  "name": "n8n",
+  "description": "n8n Claude Code plugin — shared skills, commands, and agents for n8n development"
+}
@@ -0,0 +1,67 @@
+# n8n Claude Code Plugin
+
+Shared skills, commands, and agents for n8n development.
+
+## Skills
+
+### `n8n:setup-mcps`
+
+Configures commonly used MCP servers for n8n engineers.
+
+**Usage:**
+```
+/n8n:setup-mcps
+```
+
+**What it does:**
+1. Checks which MCPs are already configured (matches by URL, not name)
+2. Presents a multi-select menu of available MCPs (Linear, Notion, Context7, Figma)
+3. For each selected MCP, asks which scope to install in:
+   - **user** (recommended) — available across all projects
+   - **local** — only in this project (`settings.local.json`)
+4. Installs using official recommended commands
+
+**Note:** Project scope is intentionally not offered since `.claude/settings.json` is tracked in git.
+
+## Design Decisions
+
+### Why a plugin instead of standalone skills?
+
+To get the `n8n:` namespace prefix for all n8n-specific skills, avoiding name
+collisions with built-in or personal skills. Claude Code only supports
+colon-namespaced skills (`n8n:setup-mcps`) through the plugin system —
+standalone `.claude/skills/` entries cannot be namespaced. This also provides a
+home for future n8n skills, commands, and agents under the same `n8n:` prefix.
+
+### Why only user and local scope (no project scope)?
+
+Project scope writes MCP config to `.claude/settings.json`, which is tracked in
+git. Since MCP credentials are personal (OAuth tokens, API keys), they should
+not end up in version control. User scope makes MCPs available across all
+projects; local scope (`settings.local.json`) keeps them project-specific but
+gitignored.
+
+### Why ask scope per MCP instead of once for all?
+
+Engineers may want different scopes for different MCPs. For example, Context7
+and Figma are useful across all projects (user scope), while Linear or Notion
+might only be needed for this project (local scope).
+
+## Plugin Structure
+
+```
+.claude/plugins/n8n/
+├── .claude-plugin/
+│   ├── marketplace.json    # Marketplace manifest
+│   └── plugin.json         # Plugin identity
+├── skills/
+│   └── sample-skill/
+│       └── SKILL.md
+└── README.md
+```
+
+## Known Issues
+
+- Plugin skill namespacing requires omitting the `name` field from SKILL.md
+  frontmatter due to a [Claude Code bug](https://github.com/anthropics/claude-code/issues/17271).
+  The directory name is used as the skill identifier instead.
@@ -0,0 +1,75 @@
+---
+description: >-
+  Configure MCP servers for n8n development. Use when the user says /setup-mcps
+  or asks to set up MCP servers for n8n.
+---
+
+# MCP Setup for n8n Development
+
+Configure commonly used MCP servers for n8n engineers.
+
+## Instructions
+
+1. First, check which MCPs are already configured by running:
+```bash
+claude mcp list
+```
+Parse the output and match by **URL/command**, not server name (users may have
+used different names). The URLs to check for:
+- Linear: `mcp.linear.app`
+- Notion: `mcp.notion.com`
+- Context7: `ctx7` or `context7-mcp`
+- Figma: `mcp.figma.com`
+
+Skip any MCP whose URL/command is already present (regardless of scope or name).
+
+2. Present the MCP selection menu using `AskUserQuestion` with `multiSelect: true`.
+Only show MCPs that are **not** already configured. If all are already configured,
+inform the user and skip the menu.
+
+| Option | Label | Description |
+|--------|-------|-------------|
+| Linear | `Linear` | Linear ticket management (HTTP, OAuth — opens browser to authenticate) |
+| Notion | `Notion` | Notion workspace integration (HTTP, OAuth — opens browser to authenticate) |
+| Context7 | `Context7` | Library documentation lookup (OAuth setup via CLI) |
+| Figma | `Figma` | Figma design integration (HTTP, OAuth — opens browser to authenticate) |
+
+3. Process each selected MCP **one at a time** in a loop. For each MCP:
+   a. Ask the user via `AskUserQuestion`: "Where should **{MCP name}** be installed?"
+      - **user** (default, recommended) — available in all projects
+      - **local** — only in this project
+   b. Run the install command for that MCP with the chosen scope
+   c. Then move to the next MCP and ask again
+
+Do NOT batch the scope question — ask separately for each MCP.
+Do NOT offer project scope — it modifies `.claude/settings.json` which is tracked in git.
+
+Commands per MCP:
+
+### Linear
+```bash
+claude mcp add -s {scope} linear-server --transport http https://mcp.linear.app/mcp
+```
+After adding, tell the user to run `/mcp` in their next session to authenticate.
+
+### Notion
+```bash
+claude mcp add -s {scope} notion --transport http https://mcp.notion.com/mcp
+```
+After adding, tell the user to run `/mcp` in their next session to authenticate.
+
+### Context7
+Tell the user to run this command themselves (it handles auth via OAuth automatically):
+
+```
+npx ctx7 setup --claude
+```
+
+### Figma
+```bash
+claude mcp add -s {scope} figma --transport http https://mcp.figma.com/mcp
+```
+After adding, tell the user to run `/mcp` in their next session to authenticate.
+
+5. After running the commands, confirm which MCPs were configured and note any
+   manual steps remaining (authentication via `/mcp`, Context7 setup).
@@ -12,5 +12,16 @@
 			"Bash(popd)",
 			"Bash(pushd:*)"
 		]
+	},
+	"extraKnownMarketplaces": {
+		"n8n": {
+			"source": {
+				"source": "directory",
+				"path": "./.claude/plugins/n8n"
+			}
+		}
+	},
+	"enabledPlugins": {
+		"n8n@n8n": true
 	}
 }