n8n-claw Documentation

n8n-claw is a self-hosted AI agent built on n8n, PostgreSQL, and Claude. It provides a natural language interface for managing tasks, long-term memory, and complex workflows.

Key capabilities include:

• Communication: Chat via Telegram or a Webhook API (for Slack, Teams, etc.).
• Memory & Knowledge: Hybrid long-term memory (semantic + full-text) and an automatic knowledge graph that tracks entities like people, companies, and events.
• Task & Project Management: Create/track tasks with priorities and maintain persistent project notes in markdown.
• Automation: Proactive heartbeats for reminders, recurring scheduled actions, and smart background checks.
• Web Capabilities: Web search (via SearXNG), web reading (via Crawl4AI), and browser automation (via Browser Use) with interactive 2FA support.
• Extensibility: Uses MCP (Model Context Protocol) to install pre-built skills or build custom API integrations on demand.
• Failure Awareness: Automatically logs workflow errors to memory and notifies you via Telegram.

The Webhook Adapter workflow translates between external message formats (Slack, Teams, Discord, Paperclip) and the agent's internal Webhook API. It uses a mapper node to normalize incoming messages and routes the response back to the original system using the metadata._responseChannel field.

Available Triggers

Adding a Custom Integration

Option 1: Custom Webhook (No-Code)

1. Open the Map Custom Input Set node in the Webhook Adapter workflow.
2. Map your app's JSON fields to the agent's schema:
   • message $\rightarrow$ your text field (e.g., $json.body.text)
   • user_id $\rightarrow$ sender identifier (e.g., $json.body.username)
   • session_id $\rightarrow$ unique conversation ID
   • source $\rightarrow$ your app's name
3. Send POST requests to /webhook/custom with the X-API-Key header.

Option 2: Advanced Trigger (Custom Routing)

1. Add a new Trigger node to the Webhook Adapter workflow.
2. Add a Map node (Code node) that outputs: { message, user_id, session_id, source, metadata: { _responseChannel: "your-system" } }.
3. Add a matching output in the Route Response switch node.
4. Add a Reply node specific to your system.

The stack runs on a single user-defined bridge network n8n-claw-net. By default, only the n8n service is exposed to the public interface.

Routing Notes:

• Most services are bound to 127.0.0.1 to prevent public access.
• If you use a managed reverse proxy (like Hostinger's), set SKIP_REVERSE_PROXY=true to prevent the installer from setting up its own Nginx/Let's Encrypt stack.

The agent includes a Library Manager that can install and manage 43+ pre-built skills from a GitHub template repository. Skills can be installed via chat commands.

Skill Types

• Native: n8n wraps a REST API as an MCP server (the default pattern).
• Bridge: Registers an existing external MCP server (e.g., DeepWiki, Zapier) via a URL and optional authentication. Supported since v1.3.0.

Common Commands

• "What skills are available?" - Lists available skills.
• "Install [skill-name]" (e.g., Install weather-openmeteo) - Fetches the template and imports the workflow into n8n.
• "Remove [skill-name]" - Uninstalls the skill.
• "Add credential for [skill-name]" - Regenerates a secure link to provide an API key.

Handling API Keys

For skills requiring authentication (e.g., news-newsapi):

1. Use the install command.
2. The agent will send a secure, one-time link via Telegram.
3. Click the link and enter your API key in the provided form.
4. The key is stored in the template_credentials table in PostgreSQL.

Security Warning: Skill credentials are currently stored unencrypted in the database. Ensure your VPS is secured via SSH (key-based auth) and that the database/API are not exposed to the public internet.

The system is composed of a central Agent (running Claude Sonnet) that orchestrates various internal modules and external services:

Core Agent Modules

• Task/Project Managers: Handle task lifecycles and persistent markdown notes.
• Memory & Knowledge Graph: Manage long-term memory and entity relationships.
• MCP Client/Builder: Interface with and create Model Context Protocol skills.
• Specialized Tools: Includes Web Search (SearXNG), Web Reader (Crawl4AI), and HTTP tools.

Background Workflows

• Heartbeat: Runs every 5 mins for recurring actions and reminders.
• Memory Consolidation: Summarizes conversations into long-term memory daily at 3am.
• Reminder Runner: Processes due reminders every 1 min.
• Error Notification: Catches and reports workflow failures to Telegram.

Integration Layers

• Telegram/Webhook: Primary input/output channels.
• Webhook Adapter: Optional layer to map Slack/Teams/Generic webhooks to the agent's internal POST endpoint.
• Internal Bridges: File Bridge (temporary binary storage) and Email Bridge (IMAP/SMTP).

The MCP Builder is an automated pipeline that creates new Model Context Protocol (MCP) tools. When triggered, it follows a sequence of searching documentation, generating code via LLM, deploying n8n workflows, and registering the tool.

The build lifecycle:

1. Research: Searches API docs (via SearXNG) and fetches content (via Jina Reader).
2. Generation: Builds a prompt and uses Claude to generate the tool logic.
3. Deployment: Assembles and deploys a two-workflow structure (MCP Server workflow + Sub-Workflow).
4. Testing: Performs an actual MCP protocol call (initialize -> notifications/initialized -> tools/call) to verify functionality. If testing fails, it attempts an LLM-driven auto-fix.
5. Registration: Adds the tool to the Supabase mcp_registry and updates the agent's mcp_instructions.

Start → Search API Docs (SearXNG) → Fetch Docs (Jina Reader)
     → BuildPrompt (LLM prompt with docs)
     → Generate Tool (Claude)
     → Assemble & Deploy
     → Create Sub-Workflow (Code node with actual logic)
     → Activate Sub-Workflow
     → Build MCP JSON
     → Create MCP Workflow (mcpTrigger + toolWorkflow)
     → Test MCP (actual MCP protocol call)
     → Register in Supabase mcp_registry
     → Update agent mcp_instructions