n8n-mcp-server


Namen8n-mcp-server JSON
Version 0.1.7 PyPI version JSON
download
home_pageNone
SummaryMCP server for n8n workflow automation
upload_time2025-07-08 17:19:16
maintainerNone
docs_urlNone
authorn8n MCP Server Contributors
requires_python>=3.8
licenseMIT
keywords n8n mcp automation workflow api
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # n8n MCP Server

[![PyPI version](https://badge.fury.io/py/n8n-mcp-server.svg)](https://badge.fury.io/py/n8n-mcp-server)
[![Python](https://img.shields.io/pypi/pyversions/n8n-mcp-server.svg)](https://pypi.org/project/n8n-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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[![PyPI version](https://badge.fury.io/py/n8n-mcp-server.svg)](https://badge.fury.io/py/n8n-mcp-server)\n[![Python](https://img.shields.io/pypi/pyversions/n8n-mcp-server.svg)](https://pypi.org/project/n8n-mcp-server/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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"
}
        
Elapsed time: 0.48605s