Skip to content
Back to search

n8n-mcp-server

MCP server that provides tools and resources for interacting with n8n API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/leonardsellem--n8n-mcp-server/badge.svg)](/listings/leonardsellem--n8n-mcp-server)

HTML

<a href="/listings/leonardsellem--n8n-mcp-server"><img src="/api/listings/leonardsellem--n8n-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Node.js 20 or later - n8n instance with API access enabled

Install from npm

npm install -g @leonardsellem/n8n-mcp-server

Install from source

# Clone the repository
git clone https://github.com/leonardsellem/n8n-mcp-server.git
cd n8n-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Optional: Install globally
npm install -g .

Docker Installation

You can also run the server using Docker:

# Pull the image
docker pull leonardsellem/n8n-mcp-server

# Run the container with your n8n API configuration
docker run -e N8N_API_URL=http://your-n8n:5678/api/v1 \
  -e N8N_API_KEY=your_n8n_api_key \
  -e N8N_WEBHOOK_USERNAME=username \
  -e N8N_WEBHOOK_PASSWORD=password \
  leonardsellem/n8n-mcp-server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 385 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # n8n MCP Server
  2. [![npm version](https://badge.fury.io/js/%40leonardsellem%2Fn8n-mcp-server.svg)](https://badge.fury.io/js/%40leonardsellem%2Fn8n-mcp-server)
  3. A Model Context Protocol (MCP) server that allows AI assistants to interact with n8n workflows through natural language.
  4. ## Overview
  5. This project provides a Model Context Protocol (MCP) server that empowers AI assistants to seamlessly interact with n8n, a popular workflow automation tool. It acts as a bridge, enabling AI assistants to programmatically manage and control n8n workflows and executions using natural language commands.
  6. ## Installation
  7. ### Prerequisites
  8. - Node.js 20 or later
  9. - n8n instance with API access enabled
  10. ### Install from npm
  11. ```bash
  12. npm install -g @leonardsellem/n8n-mcp-server
  13. ```
  14. ### Install from source
  15. ```bash
  16. # Clone the repository
  17. git clone https://github.com/leonardsellem/n8n-mcp-server.git
  18. cd n8n-mcp-server
  19. # Install dependencies
  20. npm install
  21. # Build the project
  22. npm run build
  23. # Optional: Install globally
  24. npm install -g .
  25. ```
  26. ### Docker Installation
  27. You can also run the server using Docker:
  28. ```bash
  29. # Pull the image
  30. docker pull leonardsellem/n8n-mcp-server
  31. # Run the container with your n8n API configuration
  32. docker run -e N8N_API_URL=http://your-n8n:5678/api/v1 \
  33. -e N8N_API_KEY=your_n8n_api_key \
  34. -e N8N_WEBHOOK_USERNAME=username \
  35. -e N8N_WEBHOOK_PASSWORD=password \
  36. leonardsellem/n8n-mcp-server
  37. ```
  38. ## Updating the Server
  39. How you update the server depends on how you initially installed it.
  40. ### 1. Installed globally via npm
  41. If you installed the server using `npm install -g @leonardsellem/n8n-mcp-server`:
  42. 1. Open your terminal or command prompt.
  43. 2. Run the following command to get the latest version:
  44. ```bash
  45. npm install -g @leonardsellem/n8n-mcp-server@latest
  46. ```
  47. 3. If the server is currently running (e.g., as a background process or service), you'll need to restart it for the changes to take effect.
  48. ### 2. Installed from source
  49. If you cloned the repository and installed from source:
  50. 1. Open your terminal or command prompt.
  51. 2. Navigate to the directory where you cloned the project:
  52. ```bash
  53. cd path/to/n8n-mcp-server
  54. ```
  55. 3. If you've made any local changes to the code that you want to keep, consider stashing them (optional):
  56. ```bash
  57. git stash
  58. ```
  59. You can apply them later with `git stash pop`.
  60. 4. Pull the latest changes from the repository (assuming you are on the `main` branch):
  61. ```bash
  62. git pull origin main
  63. ```
  64. If you are on a different branch, replace `main` with your branch name.
  65. 5. Install or update any changed dependencies:
  66. ```bash
  67. npm install
  68. ```
  69. 6. Rebuild the project to include the latest updates:
  70. ```bash
  71. npm run build
  72. ```
  73. 7. If you previously installed it globally from this source folder using `npm install -g .`, you might want to run this command again to update the global link:
  74. ```bash
  75. npm install -g .
  76. ```
  77. 8. Restart the server.
  78. * If you run the server directly using a command like `node build/index.js` in your AI assistant's MCP configuration, ensure the path is still correct. Using `npm install -g .` and then `n8n-mcp-server` as the command should keep this consistent.
  79. ### 3. Using Docker
  80. If you are running the server using Docker:
  81. 1. Pull the latest image from Docker Hub:
  82. ```bash
  83. docker pull leonardsellem/n8n-mcp-server:latest
  84. ```
  85. 2. Stop and remove your old container. You'll need your container's name or ID (you can find it using `docker ps`):
  86. ```bash
  87. docker stop <your_container_name_or_id>
  88. docker rm <your_container_name_or_id>
  89. ```
  90. 3. Start a new container with the updated image. Use the same `docker run` command you used previously, including all your necessary environment variables (refer to the "Docker Installation" section for an example command). For instance:
  91. ```bash
  92. docker run -e N8N_API_URL=http://your-n8n:5678/api/v1 \
  93. -e N8N_API_KEY=your_n8n_api_key \
  94. -e N8N_WEBHOOK_USERNAME=username \
  95. -e N8N_WEBHOOK_PASSWORD=password \
  96. leonardsellem/n8n-mcp-server:latest
  97. ```
  98. Ensure you use `:latest` or the specific version tag you intend to run.
  99. ## Configuration
  100. Create a `.env` file in the directory where you'll run the server, using `.env.example` as a template:
  101. ```bash
  102. cp .env.example .env
  103. ```
  104. Configure the following environment variables:
  105. | Variable | Description | Example |
  106. |----------|-------------|---------|
  107. | `N8N_API_URL` | Full URL of the n8n API, including `/api/v1` | `http://localhost:5678/api/v1` |
  108. | `N8N_API_KEY` | API key for authenticating with n8n | `n8n_api_...` |
  109. | `N8N_WEBHOOK_USERNAME` | Username for webhook authentication (if using webhooks) | `username` |
  110. | `N8N_WEBHOOK_PASSWORD` | Password for webhook authentication | `password` |
  111. | `DEBUG` | Enable debug logging (optional) | `true` or `false` |
  112. ### Generating an n8n API Key
  113. 1. Open your n8n instance in a browser
  114. 2. Go to Settings > API > API Keys
  115. 3. Create a new API key with appropriate permissions
  116. 4. Copy the key to your `.env` file
  117. ## Usage
  118. ### Running the Server
  119. From the installation directory:
  120. ```bash
  121. n8n-mcp-server
  122. ```
  123. Or if installed globally:
  124. ```bash
  125. n8n-mcp-server
  126. ```
  127. ### Integrating with AI Assistants
  128. After building the server (`npm run build`), you need to configure your AI assistant (like VS Code with the Claude extension or the Claude Desktop app) to run it. This typically involves editing a JSON configuration file.
  129. **Example Configuration (e.g., in VS Code `settings.json` or Claude Desktop `claude_desktop_config.json`):**
  130. ```json
  131. {
  132. "mcpServers": {
  133. // Give your server a unique name
  134. "n8n-local": {
  135. // Use 'node' to execute the built JavaScript file
  136. "command": "node",
  137. // Provide the *absolute path* to the built index.js file
  138. "args": [
  139. "/path/to/your/cloned/n8n-mcp-server/build/index.js"
  140. // On Windows, use double backslashes:
  141. // "C:\\path\\to\\your\\cloned\\n8n-mcp-server\\build\\index.js"
  142. ],
  143. // Environment variables needed by the server
  144. "env": {
  145. "N8N_API_URL": "http://your-n8n-instance:5678/api/v1", // Replace with your n8n URL
  146. "N8N_API_KEY": "YOUR_N8N_API_KEY", // Replace with your key
  147. // Add webhook credentials only if you plan to use webhook tools
  148. // "N8N_WEBHOOK_USERNAME": "your_webhook_user",
  149. // "N8N_WEBHOOK_PASSWORD": "your_webhook_password"
  150. },
  151. // Ensure the server is enabled
  152. "disabled": false,
  153. // Default autoApprove settings
  154. "autoApprove": []
  155. }
  156. // ... other servers might be configured here
  157. }
  158. }
  159. ```
  160. **Key Points:**
  161. * Replace `/path/to/your/cloned/n8n-mcp-server/` with the actual absolute path where you cloned and built the repository.
  162. * Use the correct path separator for your operating system (forward slashes `/` for macOS/Linux, double backslashes `\\` for Windows).
  163. * Ensure you provide the correct `N8N_API_URL` (including `/api/v1`) and `N8N_API_KEY`.
  164. * The server needs to be built (`npm run build`) before the assistant can run the `build/index.js` file.
  165. ## Available Tools
  166. The server provides the following tools:
  167. ### Using Webhooks
  168. This MCP server supports executing workflows through n8n webhooks. To use this functionality:
  169. 1. Create a webhook-triggered workflow in n8n.
  170. 2. Set up Basic Authentication on your webhook node.
  171. 3. Use the `run_webhook` tool to trigger the workflow, passing just the workflow name.
  172. Example:
  173. ```javascript
  174. const result = await useRunWebhook({
  175. workflowName: "hello-world", // Will call <n8n-url>/webhook/hello-world
  176. data: {
  177. prompt: "Hello from AI assistant!"
  178. }
  179. });
  180. ```
  181. The webhook authentication is handled automatically using the `N8N_WEBHOOK_USERNAME` and `N8N_WEBHOOK_PASSWORD` environment variables.
  182. ### Workflow Management
  183. - `workflow_list`: List all workflows
  184. - `workflow_get`: Get details of a specific workflow
  185. - `workflow_create`: Create a new workflow
  186. - `workflow_update`: Update an existing workflow
  187. - `workflow_delete`: Delete a workflow
  188. - `workflow_activate`: Activate a workflow
  189. - `workflow_deactivate`: Deactivate a workflow
  190. ### Execution Management
  191. - `execution_run`: Execute a workflow via the API
  192. - `run_webhook`: Execute a workflow via a webhook
  193. - `execution_get`: Get details of a specific execution
  194. - `execution_list`: List executions for a workflow
  195. - `execution_stop`: Stop a running execution
  196. ## Resources
  197. The server provides the following resources:
  198. - `n8n://workflows/list`: List of all workflows
  199. - `n8n://workflow/{id}`: Details of a specific workflow
  200. - `n8n://executions/{workflowId}`: List of executions for a workflow
  201. - `n8n://execution/{id}`: Details of a specific execution
  202. ## Roadmap
  203. The n8n MCP Server is a community-driven project, and its future direction will be shaped by your feedback and contributions!
  204. Currently, our roadmap is flexible and under continuous development. We believe in evolving the server based on the needs and ideas of our users.
  205. We encourage you to get involved in shaping the future of this tool:
  206. - **Suggest Features:** Have an idea for a new tool, resource, or improvement?
  207. - **Discuss Priorities:** Want to weigh in on what we should focus on next?
  208. Please share your thoughts, feature requests, and ideas by opening an issue on our [GitHub Issues page](https://github.com/leonardsellem/n8n-mcp-server/issues). Let's build a powerful tool for AI assistants together!
  209. ## Development
  210. ### Building
  211. ```bash
  212. npm run build
  213. ```
  214. ### Running in Development Mode
  215. ```bash
  216. npm run dev
  217. ```
  218. ### Testing
  219. ```bash
  220. npm test
  221. ```
  222. ### Linting
  223. ```bash
  224. npm run lint
  225. ```
  226. ## Contributing
  227. We welcome contributions from the community and are excited to see how you can help improve the n8n MCP Server! Whether you're fixing a bug, proposing a new feature, or improving documentation, your help is valued.
  228. ### Reporting Bugs
  229. If you encounter a bug, please report it by opening an issue on our [GitHub Issues page](https://github.com/leonardsellem/n8n-mcp-server/issues).
  230. When submitting a bug report, please include the following:
  231. - A clear and descriptive title.
  232. - A detailed description of the problem, including steps to reproduce the bug.
  233. - Information about your environment (e.g., Node.js version, n8n MCP Server version, operating system).
  234. - Any relevant error messages or screenshots.
  235. ### Suggesting Enhancements
  236. We're always looking for ways to make the server better. If you have an idea for an enhancement or a new feature, please open an issue on our [GitHub Issues page](https://github.com/leonardsellem/n8n-mcp-server/issues).
  237. Please provide:
  238. - A clear and descriptive title for your suggestion.
  239. - A detailed explanation of the proposed enhancement and why it would be beneficial.
  240. - Any potential use cases or examples.
  241. ### Submitting Pull Requests
  242. If you'd like to contribute code, please follow these steps:
  243. 1. **Fork the repository:** Create your own fork of the [n8n-mcp-server repository](https://github.com/leonardsellem/n8n-mcp-server).
  244. 2. **Create a branch:** Create a new branch in your fork for your changes (e.g., `git checkout -b feature/your-feature-name` or `bugfix/issue-number`).
  245. 3. **Make your changes:** Implement your feature or bug fix.
  246. * Ensure your code adheres to the existing coding style. (We use Prettier for formatting, which can be run with `npm run lint`).
  247. * Include tests for your changes if applicable. You can run tests using `npm test`.
  248. 4. **Commit your changes:** Write clear and concise commit messages.
  249. 5. **Push to your fork:** Push your changes to your forked repository.
  250. 6. **Open a Pull Request (PR):** Submit a PR to the `main` branch of the official `n8n-mcp-server` repository.
  251. * Provide a clear title and description for your PR, explaining the changes you've made and referencing any related issues.
  252. We'll review your PR as soon as possible and provide feedback. Thank you for your contribution!
  253. ## License
  254. [MIT](LICENSE)
  255. ## 🚀 Join Our Team: Call for Co-Maintainers!
  256. This project is a vibrant, community-driven tool actively used by AI enthusiasts and developers. Currently, it's maintained on a part-time basis by a passionate individual who isn't a seasoned engineer but is dedicated to bridging AI with workflow automation. To help this project flourish, ensure its long-term health, and keep up with its growing user base, we're looking for enthusiastic **co-maintainers** to join the team!
  257. ### Why Contribute?
  258. - **Learn and Grow:** Sharpen your skills in areas like TypeScript, Node.js, API integration, and AI tool development.
  259. - **Collaborate:** Work alongside other motivated developers and AI users.
  260. - **Make an Impact:** Directly shape the future of this project and help build a valuable tool for the AI community.
  261. - **Open Source:** Gain experience contributing to an open-source project.
  262. ### How You Can Help
  263. We welcome contributions in many forms! Here are some areas where you could make a big difference:
  264. - **Bug Fixing:** Help us identify and squash bugs to improve stability.
  265. - **Feature Development:** Implement new tools and functionalities based on user needs and your ideas.
  266. - **Documentation:** Improve our guides, examples, and API references to make the project more accessible.
  267. - **Testing:** Enhance our test suite (unit, integration) to ensure code quality and reliability.
  268. - **CI/CD:** Help streamline our development and deployment pipelines.
  269. - **Code Reviews:** Provide feedback on pull requests and help maintain code standards.
  270. - **Community Support:** Assist users with questions and help manage discussions.
  271. ### Get Involved!
  272. If you're excited about the intersection of AI and workflow automation, and you're looking for a rewarding open-source opportunity, we'd love to hear from you!
  273. **Ready to contribute?**
  274. 1. Check out our [GitHub Issues page](https://github.com/leonardsellem/n8n-mcp-server/issues) to find existing tasks, suggest new ideas, or express your interest in becoming a co-maintainer.
  275. 2. You can open an issue titled "Co-maintainer Application" to formally apply, or simply start contributing to existing issues.
  276. 3. Alternatively, feel free to reach out to the existing maintainers if you have questions.
  277. Let’s build the future of AI-powered workflow automation together! 🙌
  278. **Thanks to the community for the support!**
  279. [![Star History Chart](https://api.star-history.com/svg?repos=leonardsellem/n8n-mcp-server&type=Date)](https://www.star-history.com/#leonardsellem/n8n-mcp-server&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.