feat: workflow folder management (n8n_manage_folders + folder placement) v2.68.0 (czlonkowski#975)

* feat: workflow folder management (n8n_manage_folders + parentFolderId placement) v2.68.0

n8n 2.32 added workflow folder placement to the Public API (parentFolderId
on workflow create/update, personal project alias on folder create), closing
the gap that deferred this feature in June.

- New n8n_manage_folders tool: create, list, get, rename, move, delete
  (list with workflow/sub-folder counts and path breadcrumbs; move accepts
  null for the project root via n8n's '0' sentinel; delete warns that
  omitting transferToFolderId archives the folder's workflows)
- parentFolderId on n8n_create_workflow and n8n_update_full_workflow
- moveToFolder diff operation in n8n_update_partial_workflow
- Personal-project resolution: projects API when licensed; workflow
  shared[].projectId fallback only where the projects route answers 403/404
  (Community); ambiguous/truncated/absent listings error out with guidance
- Write-only placement caveats: rollback and full-update error paths state
  when a folder move in a failed update may have persisted
- 2.32-upgrade hint on schema-level 400s naming parentFolderId
- Folder list uses the fully-encoding query serializer (n8n rejects axios's
  default encoding of the JSON filter/select params; caught in live testing)
- tools_documentation overview updated (24 tools; added folders plus the
  previously missing credentials and audit entries)
- Read-only deployment recipes block the folder write actions
- Live-verified end to end against a real n8n instance: all six folder
  actions, placement at creation, moves both directions with server-side
  count confirmation, and the error paths

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: trim parentFolderId on workflow create/update schemas (Copilot review)

The folder handlers and the moveToFolder diff operation already trim folder
IDs; the workflow create/full-update schemas forwarded padded IDs verbatim,
which - placement being write-only - would fail in a hard-to-diagnose way.

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: czlonkowski

.claude/agents/n8n-mcp-tester.md

@@ -1,7 +1,7 @@
 ---
 name: n8n-mcp-tester
 description: "Use this agent when you need to test n8n-mcp functionality after implementing fixes or new features. This agent should be invoked proactively after code changes to validate that the MCP tools work correctly with real n8n workflows. The agent tests the actual MCP server tools, not just unit tests. Examples:\\n\\n<example>\\nContext: Developer has just fixed a validation bug in the n8n-mcp server\\nuser: \"I've fixed the validation issue for HTTP Request nodes\"\\nassistant: \"I've completed the fix. Now let me build the project and then test it.\"\\n<builds project>\\nassistant: \"Project built successfully. Please reload the MCP server in Claude Desktop to apply the changes.\"\\nuser: \"Reloaded\"\\nassistant: \"Great! Now let me invoke the n8n-mcp-tester agent to verify the fix works correctly.\"\\n<commentary>\\nSince a fix has been implemented and the MCP server reloaded, use the n8n-mcp-tester agent to validate the fix works in real-world usage.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: Developer has added a new MCP tool for workflow validation\\nuser: \"I've implemented the new workflow validation tool\"\\nassistant: \"Implementation complete. Let me build and prepare for testing.\"\\n<builds project>\\nassistant: \"Build successful. Please reload the MCP server to load the new tool.\"\\nuser: \"Done\"\\nassistant: \"Perfect! I'll now use the n8n-mcp-tester agent to test the new workflow validation tool.\"\\n<commentary>\\nAfter implementing new MCP functionality and reloading the server, invoke n8n-mcp-tester to verify it works correctly.\\n</commentary>\\n</example>"
-tools: "Glob, Grep, Read, WebFetch, WebSearch, ListMcpResourcesTool, ReadMcpResourceTool, Bash, mcp__context7__query-docs, mcp__context7__resolve-library-id, mcp__n8n-mcp-testing__get_node, mcp__n8n-mcp-testing__get_template, mcp__n8n-mcp-testing__n8n_autofix_workflow, mcp__n8n-mcp-testing__n8n_create_workflow, mcp__n8n-mcp-testing__n8n_delete_workflow, mcp__n8n-mcp-testing__n8n_deploy_template, mcp__n8n-mcp-testing__n8n_executions, mcp__n8n-mcp-testing__n8n_get_workflow, mcp__n8n-mcp-testing__n8n_health_check, mcp__n8n-mcp-testing__n8n_list_workflows, mcp__n8n-mcp-testing__n8n_manage_datatable, mcp__n8n-mcp-testing__n8n_test_workflow, mcp__n8n-mcp-testing__n8n_update_full_workflow, mcp__n8n-mcp-testing__n8n_update_partial_workflow, mcp__n8n-mcp-testing__n8n_validate_workflow, mcp__n8n-mcp-testing__n8n_workflow_versions, mcp__n8n-mcp-testing__search_nodes, mcp__n8n-mcp-testing__search_templates, mcp__n8n-mcp-testing__tools_documentation, mcp__n8n-mcp-testing__validate_node, mcp__n8n-mcp-testing__validate_workflow, mcp__plugin_postgres-best-practices_supabase__authenticate, mcp__supabase-telemetry__apply_migration, mcp__supabase-telemetry__create_branch, mcp__supabase-telemetry__delete_branch, mcp__supabase-telemetry__deploy_edge_function, mcp__supabase-telemetry__execute_sql, mcp__supabase-telemetry__generate_typescript_types, mcp__supabase-telemetry__get_advisors, mcp__supabase-telemetry__get_edge_function, mcp__supabase-telemetry__get_logs, mcp__supabase-telemetry__get_project_url, mcp__supabase-telemetry__get_publishable_keys, mcp__supabase-telemetry__list_branches, mcp__supabase-telemetry__list_edge_functions, mcp__supabase-telemetry__list_extensions, mcp__supabase-telemetry__list_migrations, mcp__supabase-telemetry__list_tables, mcp__supabase-telemetry__merge_branch, mcp__supabase-telemetry__rebase_branch, mcp__supabase-telemetry__reset_branch, mcp__supabase-telemetry__search_docs"
+tools: "Glob, Grep, Read, WebFetch, WebSearch, ListMcpResourcesTool, ReadMcpResourceTool, Bash, mcp__context7__query-docs, mcp__context7__resolve-library-id, mcp__n8n-mcp-testing__get_node, mcp__n8n-mcp-testing__get_template, mcp__n8n-mcp-testing__n8n_autofix_workflow, mcp__n8n-mcp-testing__n8n_create_workflow, mcp__n8n-mcp-testing__n8n_delete_workflow, mcp__n8n-mcp-testing__n8n_deploy_template, mcp__n8n-mcp-testing__n8n_executions, mcp__n8n-mcp-testing__n8n_get_workflow, mcp__n8n-mcp-testing__n8n_health_check, mcp__n8n-mcp-testing__n8n_list_workflows, mcp__n8n-mcp-testing__n8n_manage_datatable, mcp__n8n-mcp-testing__n8n_manage_folders, mcp__n8n-mcp-testing__n8n_test_workflow, mcp__n8n-mcp-testing__n8n_update_full_workflow, mcp__n8n-mcp-testing__n8n_update_partial_workflow, mcp__n8n-mcp-testing__n8n_validate_workflow, mcp__n8n-mcp-testing__n8n_workflow_versions, mcp__n8n-mcp-testing__search_nodes, mcp__n8n-mcp-testing__search_templates, mcp__n8n-mcp-testing__tools_documentation, mcp__n8n-mcp-testing__validate_node, mcp__n8n-mcp-testing__validate_workflow, mcp__plugin_postgres-best-practices_supabase__authenticate, mcp__supabase-telemetry__apply_migration, mcp__supabase-telemetry__create_branch, mcp__supabase-telemetry__delete_branch, mcp__supabase-telemetry__deploy_edge_function, mcp__supabase-telemetry__execute_sql, mcp__supabase-telemetry__generate_typescript_types, mcp__supabase-telemetry__get_advisors, mcp__supabase-telemetry__get_edge_function, mcp__supabase-telemetry__get_logs, mcp__supabase-telemetry__get_project_url, mcp__supabase-telemetry__get_publishable_keys, mcp__supabase-telemetry__list_branches, mcp__supabase-telemetry__list_edge_functions, mcp__supabase-telemetry__list_extensions, mcp__supabase-telemetry__list_migrations, mcp__supabase-telemetry__list_tables, mcp__supabase-telemetry__merge_branch, mcp__supabase-telemetry__rebase_branch, mcp__supabase-telemetry__reset_branch, mcp__supabase-telemetry__search_docs"
 model: sonnet
 ---
 You are n8n-mcp-tester, a specialized testing agent for the n8n Model Context Protocol (MCP) server. You validate that MCP tools and functionality work correctly in real-world scenarios after fixes or new features are implemented.

.env.example

@@ -133,10 +133,11 @@ AUTH_TOKEN=your-secure-token-here
 # Eligible tools and their operations:
 #   n8n_executions        — action: get, list, delete
 #   n8n_evaluations       — action: list_runs, get_run, list_cases, run, cancel
+#   n8n_manage_folders    — action: create, list, get, rename, move, delete
 #   n8n_workflow_versions — mode: list, get, rollback, delete, prune
 #
 # Read-only deployment recipe (blocks all destructive operations):
-# DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete;n8n_evaluations:run,cancel
+# DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete;n8n_evaluations:run,cancel;n8n_manage_folders:create,rename,move,delete
 #
 # Combine with n8n API key RBAC for defence in depth.
 # Default: (empty - all operations enabled)

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.68.0] - 2026-08-04
+
+### Added
+
+- **Workflow folder management: new `n8n_manage_folders` tool.** Folders have been in n8n's Public API since 2.19, but nothing could place a workflow into one until n8n 2.32 added `parentFolderId` to workflow writes — the gap that had kept this feature deferred. The tool covers `create`, `list`, `get`, `rename`, `move`, and `delete`: list returns per-folder workflow/sub-folder counts and path breadcrumbs, get returns recursive totals, move accepts `null` for the project root (mapped to n8n's `'0'` sentinel), and delete warns that omitting `transferToFolderId` archives the folder's workflows (`'0'` transfers them to the project root instead). `projectId` defaults to `personal`: folder creation passes the alias through (n8n resolves it server-side, 2.32+), while the other actions resolve it via the projects API when licensed, falling back to a workflow's owning project only where that is sound — the projects route answering 403/404 (Community, which has exactly one project). A successful projects listing with zero or several visible personal projects, or one truncated by pagination, errors out with guidance instead of guessing another project's ID, and the resolution is cached per client, which is per instance. All four write actions are registered for `DISABLED_TOOL_OPERATIONS`; the read-only deployment recipes in the README, `.env.example`, and the HTTP deployment guide block them.
+- **Workflow folder placement on the workflow tools (n8n 2.32+).** `n8n_create_workflow` accepts `parentFolderId` to create a workflow directly inside a folder; `n8n_update_partial_workflow` gains a `moveToFolder` operation (`parentFolderId`: folder ID, or `null` for the project root); `n8n_update_full_workflow` accepts the same field. n8n treats the field as write-only — a workflow's folder can never be read back, so the diff handler's rollback path and the full-update error path now say explicitly when a folder move in a failed update may have persisted rather than claiming full restoration. On instances older than 2.32, the schema-level 400 naming `parentFolderId` earns an upgrade hint; a semantic 400 (e.g. a deleted folder ID) on a supporting instance does not. Blank strings and `null` from lossy MCP clients are handled throughout (issue #774 pattern), including `parentFolderId: null` on folder create/list, which the published `string|null` schema allows as "no parent".
+
+### Fixed
+
+- **Folder list requests survive n8n's strict query validation.** The `filter`/`select` parameters travel as JSON in the query string; axios's default serializer leaves reserved characters raw and n8n rejects the request with "Parameter 'filter' must be url encoded" (caught in live testing). The folder list now uses the same fully-encoding serializer as the data-table row endpoints (renamed to `serializeQueryParams`).
+- **The `tools_documentation` overview lists all current tools.** The hardcoded category list was stale: it now includes `n8n_manage_credentials`, `n8n_audit_instance`, and the new `n8n_manage_folders`, with corrected counts (24 tools, 18 n8n API tools).
+
 ## [2.67.3] - 2026-08-03
 
 ### Changed

README.md

@@ -390,6 +390,9 @@ These tools require `N8N_API_URL` and `N8N_API_KEY` in your configuration.
 - **`n8n_executions`** - Unified execution management (list, get, delete)
 - **`n8n_evaluations`** - Run and read evaluation test runs (list runs, aggregated metrics, per-case results on n8n 2.30+; trigger and cancel on 2.32+)
 
+#### Folder Management
+- **`n8n_manage_folders`** - Manage workflow folders (create, list, get, rename, move, delete; n8n 2.19+). Place workflows into folders via `n8n_create_workflow`'s `parentFolderId` or `n8n_update_partial_workflow`'s `moveToFolder` operation (n8n 2.32+)
+
 #### Data Table Management
 - **`n8n_manage_datatable`** - Manage n8n data tables and rows (list, get, create, update, delete)
 
@@ -413,7 +416,7 @@ DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_w
 For tools that bundle read and write operations under one name, block only the destructive operations while keeping `list` and `get`:
 
 ```bash
-DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete;n8n_evaluations:run,cancel
+DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete;n8n_evaluations:run,cancel;n8n_manage_folders:create,rename,move,delete
 ```
 
 Combine with a read-only n8n API key (Settings → API in your n8n instance) for defence in depth. See [Read-Only Deployment Recipe](./docs/HTTP_DEPLOYMENT.md#read-only-deployment-recipe) for the full setup guide.

docs/HTTP_DEPLOYMENT.md

@@ -889,10 +889,10 @@ Some tools are write/destructive or handle sensitive data and should be removed
 DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_workflow,n8n_delete_workflow,n8n_autofix_workflow,n8n_deploy_template,n8n_test_workflow,n8n_manage_credentials,n8n_manage_datatable
 ```
 
-Three tools bundle read and write operations under a single name. Use `DISABLED_TOOL_OPERATIONS` to block only their destructive branches while keeping `list` and `get`:
+Four tools bundle read and write operations under a single name. Use `DISABLED_TOOL_OPERATIONS` to block only their destructive branches while keeping `list` and `get`:
 
 ```bash
-DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete;n8n_evaluations:run,cancel
+DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete;n8n_evaluations:run,cancel;n8n_manage_folders:create,rename,move,delete
 ```
 
 The operation parameter enum in the tool schema is updated to exclude disabled values, reducing the likelihood the model attempts them. Any attempt that does reach the server is rejected at dispatch before the handler runs.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.67.3",
+  "version": "2.68.0",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",