What is N8n Uvx

n8n-uvx is a self-hosted integration for MCP UVX servers that allows users to run UVX-powered MCP servers locally within their N8N workflows using Docker, eliminating the need for cloud dependency.

Use cases

Use cases include automating data processing tasks, integrating various APIs with MCP UVX servers, and managing local workflows that require real-time data handling and processing.

How to use

To use n8n-uvx, clone the repository, set up the environment variables, and run the Docker Compose setup to integrate MCP UVX servers into your local N8N instance.

Key features

Key features include a Docker-first approach for portability, installation of Astral CLI tools for MCP server management, persistent data volumes for N8N workflows and MCP assets, and a local-only execution environment for enhanced security.

Where to use

n8n-uvx is ideal for developers and businesses looking to automate workflows that require MCP UVX server integration without relying on external cloud services, making it suitable for sensitive or offline environments.

Repository Description

Self-hosted N8N integration for MCP UVX servers via Docker—run UVX-powered MCP servers locally in your N8N workflows without any cloud dependency.

n8n-uvx

A Dockerized setup that integrates Astral UV/UVX MCP servers directly into your local N8N instance—no external cloud services required.

Table of Contents

• Introduction
• Features
• Prerequisites
• Installation
• Dockerfile Overview
• Environment Variables (.env)
• Docker Compose Setup
• Configuration
• Usage
• Additional Resources
• Contributing
• License

Introduction

This repository provides everything you need to self-host MCP UVX servers inside your N8N workflows using Docker. It installs the Astral UV/UVX CLI tools into an N8N container, exposes a data directory for MCP assets, and configures a Docker Compose service for seamless local automation.

Features

• 🐳 Docker-First: Fully containerized setup for portability and isolation.
• ⚙️ Astral CLI Tools: Installs uv and uvx via Astral’s installer for MCP server management.
• 📁 Persistent Data Volumes: Separate directories for N8N workflows and MCP assets.
• 🔒 Local-Only: Keep all data and execution on your machine—ideal for sensitive or offline environments.

Prerequisites

• Docker (20.10+)
• Docker Compose
• A basic local N8N setup (v0.x or later)
• Familiarity with Docker and environment variables

Installation

1. Clone this repository

   git clone https://github.com/The-AI-Workshops/n8n-uvx.git
   cd n8n-uvx
   

2. Copy .env.example to .env and edit it (update variables as needed — see Environment Variables).

3. Build the Docker image:

   docker build -t n8n-uvx .
   

4. Launch with Docker Compose:

   docker-compose up -d
   

**Alternative with **docker run (no Compose):

docker run -d \
  --name n8n-uvx \
  -p ${N8N_PORT}:5678 \
  -e N8N_BASIC_AUTH_ACTIVE=${N8N_BASIC_AUTH_ACTIVE} \
  -e N8N_BASIC_AUTH_USER=${N8N_BASIC_AUTH_USER} \
  -e N8N_BASIC_AUTH_PASSWORD=${N8N_BASIC_AUTH_PASSWORD} \
  -e N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=${N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE} \
  -v ${N8N_DATA_DIR}:/home/node/.n8n \
  -v ${MCP_DATA_DIR}:/data/mcp \
  n8n-uvx

Dockerfile Overview

The Dockerfile extends the official N8N image and includes steps to install system dependencies and Astral UV/UVX:

FROM n8nio/n8n:latest

USER root

# Install necessary system packages
RUN apk add --no-cache \
    curl \
    git \
    build-base \
    chromium \
    bash \
    tar \
    xz \
    util-linux \
    coreutils

# Install Astral uv/uvx and make available system-wide
RUN curl -Ls https://astral.sh/uv/install.sh | bash \
    && cp /root/.local/bin/uv /usr/local/bin/uv \
    && cp /root/.local/bin/uvx /usr/local/bin/uvx \
    && chmod a+rx /usr/local/bin/uv /usr/local/bin/uvx \
    && mkdir -p /data/mcp \
    && chown -R node:node /data/mcp

ENV PATH="/usr/local/bin:/root/.local/bin:${PATH}"

USER node

Environment Variables (.env)

Create a .env at the project root with these values:

# N8N Settings
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=admin123
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
N8N_PORT=5678

# Data Volume Paths
N8N_DATA_DIR=./data
MCP_DATA_DIR=./mcp

Docker Compose Setup

Use explicit variable mappings in docker-compose.yml:

version: '3.8'

services:
  n8n:
    build: .
    ports:
      - "${N8N_PORT}:5678"
    environment:
      # N8N Core
      N8N_BASIC_AUTH_ACTIVE:           "${N8N_BASIC_AUTH_ACTIVE}"
      N8N_BASIC_AUTH_USER:             "${N8N_BASIC_AUTH_USER}"
      N8N_BASIC_AUTH_PASSWORD:         "${N8N_BASIC_AUTH_PASSWORD}"
      N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE: "${N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE}"

      # Volume Paths (for clarity)
      N8N_DATA_DIR: "${N8N_DATA_DIR}"
      MCP_DATA_DIR: "${MCP_DATA_DIR}"
    volumes:
      - "${N8N_DATA_DIR}:/home/node/.n8n"
      - "${MCP_DATA_DIR}:/data/mcp"

Configuration

• Ports: Adjust N8N_PORT if port 5678 is in use.
• Volumes: Ensure ./data and ./mcp exist with proper permissions.
• Authentication: Change default admin123 password to a secure secret.

Usage

1. Visit http://localhost:${N8N_PORT} and log in.
2. Install the MCP Client node if needed: Settings > Community Nodes > n8n-nodes-mcp-client.
3. Create workflows using the uv/uvx CLI commands via N8N’s Execute Command node or custom nodes.

Additional Resources

• Astral UV/UVX CLI: https://astral.sh/docs/uv
• Awesome MCP Servers: https://github.com/punkpeye/awesome-mcp-servers
• N8N Docker Docs: https://docs.n8n.io/getting-started/docker/

Contributing

1. Fork the repo.
2. Create a branch (git checkout -b feature/xyz).
3. Commit changes (git commit -m "Add feature").
4. Push to origin and open a PR.

License

This project is licensed under the MIT License.