# n8n MCP Server
[](https://badge.fury.io/py/n8n-mcp-server)
[](https://pypi.org/project/n8n-mcp-server/)
[](https://opensource.org/licenses/MIT)
Connect your AI assistant to n8n workflow automation platform through the Model Context Protocol. This server provides direct access to n8n's entire REST API, enabling AI-powered workflow management, execution monitoring, and automation control.
## Quick Start
1. Install with uvx: `uvx n8n-mcp-server`
2. Add to your Claude Desktop config:
```json
{
"mcpServers": {
"n8n": {
"command": "uvx",
"args": ["n8n-mcp-server"],
"env": {
"N8N_HOST": "https://your-n8n.com",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
3. Restart Claude Desktop and start automating!
## Features
- **40+ Auto-generated Tools** - Full access to n8n's REST API
- **Smart JSON Handling** - Automatically fixes JSON serialization issues
- **Custom Lightweight Tools** - Optimized tools for working within token limits
- **Full Authentication** - Secure API key authentication
- **Built with FastMCP** - Reliable, high-performance MCP implementation
### Custom Tools for Large Workflows
The server includes custom tools designed for handling large workflows that might exceed token limits:
- **`list_workflows_minimal`** - Lists workflows with only essential metadata (id, name, active, dates, tags)
- **`get_workflow_summary`** - Gets workflow info with node/connection counts instead of full data
- **`partial_update_workflow`** - Updates specific nodes without sending the entire workflow
- **`add_nodes_to_workflow`** - Adds new nodes and automatically handles connection rewiring
## Prerequisites
- Python 3.8 or higher
- An n8n instance with API access enabled
- n8n API key
## Installation
### Using uvx (Recommended)
The easiest way to use n8n MCP Server is with [uvx](https://github.com/astral-sh/uv), which runs the server in an isolated environment:
```json
{
"mcpServers": {
"n8n": {
"command": "uvx",
"args": ["n8n-mcp-server"],
"env": {
"N8N_HOST": "https://your-n8n-instance.com",
"N8N_API_KEY": "your-api-key-here"
}
}
}
}
```
### Using pip
```bash
pip install n8n-mcp-server
```
### From Source
1. Clone this repository:
```bash
git clone https://github.com/andrewlwn77/n8n-mcp-server.git
cd n8n-mcp-server
```
2. Install in development mode:
```bash
pip install -e .
```
## Configuration
The server requires two environment variables:
- `N8N_HOST`: Your n8n instance URL (e.g., https://n8n.example.com)
- `N8N_API_KEY`: Your n8n API key
You can provide these through:
1. **Environment variables in your MCP client configuration** (recommended for uvx)
2. **A `.env` file** in your working directory:
```bash
N8N_HOST=https://your-n8n-instance.com
N8N_API_KEY=your-api-key-here
```
## Usage
### Running the Server
Start the MCP server:
```bash
n8n-mcp-server
```
Or if running from source:
```bash
python -m n8n_mcp
```
The server will:
1. Connect to your n8n instance
2. Fetch the OpenAPI specification
3. Generate MCP tools for all available endpoints
4. Start listening for MCP requests
### What Can You Do?
With n8n MCP Server, your AI assistant can:
- **Manage Workflows** - Create, update, delete, and organize automation workflows
- **Execute Workflows** - Trigger workflow runs and pass custom data
- **Monitor Executions** - Check workflow status, review logs, and handle errors
- **Work with Credentials** - Safely manage authentication for external services
- **Handle Large Workflows** - Use optimized tools designed for token limits
- **Update Specific Nodes** - Modify individual workflow nodes without affecting others
- **Add Nodes Dynamically** - Insert new nodes and automatically rewire connections
Example commands you can give your AI assistant:
- "List all my active workflows"
- "Execute the 'Daily Report' workflow with today's date"
- "Show me failed executions from the last 24 hours"
- "Add a Slack notification node to my error handling workflow"
- "Update the schedule trigger to run every hour instead of daily"
## MCP Client Configuration
### Claude Desktop
Add to your Claude Desktop configuration:
#### Using uvx (Recommended)
```json
{
"mcpServers": {
"n8n": {
"command": "uvx",
"args": ["n8n-mcp-server"],
"env": {
"N8N_HOST": "https://your-n8n-instance.com",
"N8N_API_KEY": "your-api-key-here"
}
}
}
}
```
#### Using pip installation
```json
{
"mcpServers": {
"n8n": {
"command": "n8n-mcp-server",
"env": {
"N8N_HOST": "https://your-n8n-instance.com",
"N8N_API_KEY": "your-api-key-here"
}
}
}
}
```
#### Using .env file
If you have a `.env` file in your working directory:
```json
{
"mcpServers": {
"n8n": {
"command": "n8n-mcp-server"
}
}
}
```
## Security Notes
- Keep your `.env` file secure and never commit it to version control
- Use environment-specific API keys with minimal required permissions
- Consider using read-only API keys for development/testing
## Troubleshooting
### No Tools Showing in MCP Client
- Ensure the server started successfully
- Check that your n8n credentials are correct
- Verify the MCP client can connect to the server
### Connection Failed
- Verify your n8n instance URL is correct and includes the protocol (https://)
- Check that your API key is valid and has the necessary permissions
- Ensure your n8n instance has API access enabled
- Make sure the n8n instance is accessible from your network
### Missing Tools
- The available tools depend on your n8n instance version and configuration
- Some endpoints may require admin permissions
- Check the server logs for any errors during initialization
## Related Documentation
- [n8n API Documentation](https://docs.n8n.io/api/)
- [n8n Authentication](https://docs.n8n.io/api/authentication/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP Framework](https://github.com/dotinc/fastmcp)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "n8n-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "n8n, mcp, automation, workflow, api",
"author": "n8n MCP Server Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ad/54/617c1663f35b1911e48f1169a3d3d3bae1e3ba2a183fb7e3d5e2df47167b/n8n_mcp_server-0.1.7.tar.gz",
"platform": null,
"description": "# n8n MCP Server\n\n[](https://badge.fury.io/py/n8n-mcp-server)\n[](https://pypi.org/project/n8n-mcp-server/)\n[](https://opensource.org/licenses/MIT)\n\nConnect your AI assistant to n8n workflow automation platform through the Model Context Protocol. This server provides direct access to n8n's entire REST API, enabling AI-powered workflow management, execution monitoring, and automation control.\n\n## Quick Start\n\n1. Install with uvx: `uvx n8n-mcp-server`\n2. Add to your Claude Desktop config:\n```json\n{\n \"mcpServers\": {\n \"n8n\": {\n \"command\": \"uvx\",\n \"args\": [\"n8n-mcp-server\"],\n \"env\": {\n \"N8N_HOST\": \"https://your-n8n.com\",\n \"N8N_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n3. Restart Claude Desktop and start automating!\n\n## Features\n\n- **40+ Auto-generated Tools** - Full access to n8n's REST API\n- **Smart JSON Handling** - Automatically fixes JSON serialization issues\n- **Custom Lightweight Tools** - Optimized tools for working within token limits\n- **Full Authentication** - Secure API key authentication\n- **Built with FastMCP** - Reliable, high-performance MCP implementation\n\n### Custom Tools for Large Workflows\n\nThe server includes custom tools designed for handling large workflows that might exceed token limits:\n\n- **`list_workflows_minimal`** - Lists workflows with only essential metadata (id, name, active, dates, tags)\n- **`get_workflow_summary`** - Gets workflow info with node/connection counts instead of full data\n- **`partial_update_workflow`** - Updates specific nodes without sending the entire workflow\n- **`add_nodes_to_workflow`** - Adds new nodes and automatically handles connection rewiring\n\n## Prerequisites\n\n- Python 3.8 or higher\n- An n8n instance with API access enabled\n- n8n API key\n\n## Installation\n\n### Using uvx (Recommended)\n\nThe easiest way to use n8n MCP Server is with [uvx](https://github.com/astral-sh/uv), which runs the server in an isolated environment:\n\n```json\n{\n \"mcpServers\": {\n \"n8n\": {\n \"command\": \"uvx\",\n \"args\": [\"n8n-mcp-server\"],\n \"env\": {\n \"N8N_HOST\": \"https://your-n8n-instance.com\",\n \"N8N_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n### Using pip\n\n```bash\npip install n8n-mcp-server\n```\n\n### From Source\n\n1. Clone this repository:\n```bash\ngit clone https://github.com/andrewlwn77/n8n-mcp-server.git\ncd n8n-mcp-server\n```\n\n2. Install in development mode:\n```bash\npip install -e .\n```\n\n## Configuration\n\nThe server requires two environment variables:\n\n- `N8N_HOST`: Your n8n instance URL (e.g., https://n8n.example.com)\n- `N8N_API_KEY`: Your n8n API key\n\nYou can provide these through:\n\n1. **Environment variables in your MCP client configuration** (recommended for uvx)\n2. **A `.env` file** in your working directory:\n\n```bash\nN8N_HOST=https://your-n8n-instance.com\nN8N_API_KEY=your-api-key-here\n```\n\n## Usage\n\n### Running the Server\n\nStart the MCP server:\n```bash\nn8n-mcp-server\n```\n\nOr if running from source:\n```bash\npython -m n8n_mcp\n```\n\nThe server will:\n1. Connect to your n8n instance\n2. Fetch the OpenAPI specification\n3. Generate MCP tools for all available endpoints\n4. Start listening for MCP requests\n\n\n### What Can You Do?\n\nWith n8n MCP Server, your AI assistant can:\n\n- **Manage Workflows** - Create, update, delete, and organize automation workflows\n- **Execute Workflows** - Trigger workflow runs and pass custom data\n- **Monitor Executions** - Check workflow status, review logs, and handle errors\n- **Work with Credentials** - Safely manage authentication for external services\n- **Handle Large Workflows** - Use optimized tools designed for token limits\n- **Update Specific Nodes** - Modify individual workflow nodes without affecting others\n- **Add Nodes Dynamically** - Insert new nodes and automatically rewire connections\n\nExample commands you can give your AI assistant:\n- \"List all my active workflows\"\n- \"Execute the 'Daily Report' workflow with today's date\"\n- \"Show me failed executions from the last 24 hours\"\n- \"Add a Slack notification node to my error handling workflow\"\n- \"Update the schedule trigger to run every hour instead of daily\"\n\n## MCP Client Configuration\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration:\n\n#### Using uvx (Recommended)\n```json\n{\n \"mcpServers\": {\n \"n8n\": {\n \"command\": \"uvx\",\n \"args\": [\"n8n-mcp-server\"],\n \"env\": {\n \"N8N_HOST\": \"https://your-n8n-instance.com\",\n \"N8N_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n#### Using pip installation\n```json\n{\n \"mcpServers\": {\n \"n8n\": {\n \"command\": \"n8n-mcp-server\",\n \"env\": {\n \"N8N_HOST\": \"https://your-n8n-instance.com\",\n \"N8N_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n#### Using .env file\nIf you have a `.env` file in your working directory:\n```json\n{\n \"mcpServers\": {\n \"n8n\": {\n \"command\": \"n8n-mcp-server\"\n }\n }\n}\n```\n\n## Security Notes\n\n- Keep your `.env` file secure and never commit it to version control\n- Use environment-specific API keys with minimal required permissions\n- Consider using read-only API keys for development/testing\n\n## Troubleshooting\n\n### No Tools Showing in MCP Client\n- Ensure the server started successfully\n- Check that your n8n credentials are correct\n- Verify the MCP client can connect to the server\n\n### Connection Failed\n- Verify your n8n instance URL is correct and includes the protocol (https://)\n- Check that your API key is valid and has the necessary permissions\n- Ensure your n8n instance has API access enabled\n- Make sure the n8n instance is accessible from your network\n\n### Missing Tools\n- The available tools depend on your n8n instance version and configuration\n- Some endpoints may require admin permissions\n- Check the server logs for any errors during initialization\n\n## Related Documentation\n\n- [n8n API Documentation](https://docs.n8n.io/api/)\n- [n8n Authentication](https://docs.n8n.io/api/authentication/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [FastMCP Framework](https://github.com/dotinc/fastmcp)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for n8n workflow automation",
"version": "0.1.7",
"project_urls": {
"Documentation": "https://github.com/andrewlwn77/n8n-mcp-server#readme",
"Homepage": "https://github.com/andrewlwn77/n8n-mcp-server",
"Issues": "https://github.com/andrewlwn77/n8n-mcp-server/issues",
"Repository": "https://github.com/andrewlwn77/n8n-mcp-server.git"
},
"split_keywords": [
"n8n",
" mcp",
" automation",
" workflow",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5d97262c37d77d45acd46498e7f2505f15a26539c7fe1dc7d9cfe794674660cc",
"md5": "07486f54b85dfed4907973959cad834a",
"sha256": "bb489c020fe6ae36db4a959be964198494734df0b20b87af9e0e8482b0dfd9b3"
},
"downloads": -1,
"filename": "n8n_mcp_server-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "07486f54b85dfed4907973959cad834a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 29494,
"upload_time": "2025-07-08T17:19:15",
"upload_time_iso_8601": "2025-07-08T17:19:15.808506Z",
"url": "https://files.pythonhosted.org/packages/5d/97/262c37d77d45acd46498e7f2505f15a26539c7fe1dc7d9cfe794674660cc/n8n_mcp_server-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ad54617c1663f35b1911e48f1169a3d3d3bae1e3ba2a183fb7e3d5e2df47167b",
"md5": "44fedc45ffbc9e1d931b453145a2f57d",
"sha256": "41087ebfa25c1ddbe02e752a637a3013b59205783fa7de97cf82fd124d91c35e"
},
"downloads": -1,
"filename": "n8n_mcp_server-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "44fedc45ffbc9e1d931b453145a2f57d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 37924,
"upload_time": "2025-07-08T17:19:16",
"upload_time_iso_8601": "2025-07-08T17:19:16.806204Z",
"url": "https://files.pythonhosted.org/packages/ad/54/617c1663f35b1911e48f1169a3d3d3bae1e3ba2a183fb7e3d5e2df47167b/n8n_mcp_server-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 17:19:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andrewlwn77",
"github_project": "n8n-mcp-server#readme",
"github_not_found": true,
"lcname": "n8n-mcp-server"
}
JSON
