Manual Installation from Source¶

This guide explains how to install and build the n8n MCP Workflow Builder from source code, giving you full control over the build process and enabling custom modifications.

When to Use Manual Installation¶

Choose manual installation if you:

• ✅ Want to customize the source code
• ✅ Need to debug or contribute to the project
• ✅ Prefer building from source for security auditing
• ✅ Are working with the latest development features
• ✅ Need to build for specific platforms or environments

For most users, NPM installation is recommended.

Prerequisites¶

Before starting, ensure you have the following tools installed:

Required Tools¶

Verification Commands¶

Check your installed versions:

# Check Git version
git --version
# Expected: git version 2.x.x or higher

# Check Node.js version
node --version
# Expected: v14.x.x or higher (v18.x.x or v20.x.x recommended)

# Check npm version
npm --version
# Expected: 7.x.x or higher (9.x.x or 10.x.x recommended)

Additional Requirements¶

• Command line knowledge - Basic familiarity with terminal/command prompt
• GitHub account (optional) - For contributing changes
• 5-10 minutes - Estimated time for complete setup

Installation Steps¶

Step 1: Clone the Repository¶

Clone the GitHub repository to your local machine:

# Clone via HTTPS (recommended for most users)
git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git

# OR clone via SSH (if you have SSH keys configured)
git clone git@github.com:salacoste/mcp-n8n-workflow-builder.git

# Navigate to project directory
cd mcp-n8n-workflow-builder

Expected Output:

Cloning into 'mcp-n8n-workflow-builder'...
remote: Enumerating objects: 342, done.
remote: Counting objects: 100% (342/342), done.
remote: Compressing objects: 100% (156/156), done.
remote: Total 342 (delta 178), reused 312 (delta 165)
Receiving objects: 100% (342/342), 2.15 MiB | 5.23 MiB/s, done.
Resolving deltas: 100% (178/178), done.

Verification:

# Verify repository was cloned successfully
ls -la

# You should see:
# - src/           (TypeScript source code)
# - package.json   (Dependencies and scripts)
# - tsconfig.json  (TypeScript configuration)
# - README.md      (Documentation)

Step 2: Select Branch (Optional)¶

The repository has different branches for different purposes:

For stable installation, use main (default):

# Verify you're on main branch
git branch

# Output should show:
# * main

For latest features, switch to develop:

# Switch to develop branch
git checkout develop

# Verify
git branch

# Output should show:
# * develop

Step 3: Install Dependencies¶

Install all required npm packages:

npm install

Expected Output:

added 45 packages, and audited 46 packages in 12s

12 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

What Gets Installed:

Step 4: Build from Source¶

Compile TypeScript source code to JavaScript:

# Clean previous build artifacts (if any)
npm run clean

# Build the project
npm run build

Expected Output:

> @kernel.salacoste/n8n-workflow-builder@0.9.1 build
> tsc

# (TypeScript compilation happens silently if successful)

Verification:

# Check build output directory
ls -la build/

# You should see compiled JavaScript files:
# - index.js
# - config/
# - services/
# - types/
# - utils/

Build Directory Structure:

build/
├── index.js              # Main entry point
├── config/
│   └── configLoader.js   # Configuration loading
├── services/
│   ├── environmentManager.js
│   ├── n8nApiWrapper.js
│   ├── workflowBuilder.js
│   └── promptsService.js
├── types/
│   └── api.js            # Type definitions
└── utils/
    └── validation.js     # Validation utilities

Step 5: Configure the Server¶

Before running, configure your n8n connection:

# Create .env file
cat > .env << 'EOF'
N8N_HOST=https://your-instance.app.n8n.cloud
N8N_API_KEY=your_api_key_here
MCP_PORT=3456
DEBUG=false
EOF

# Create .config.json
cat > .config.json << 'EOF'
{
  "environments": {
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "your_dev_api_key"
    }
  },
  "defaultEnv": "development"
}
EOF

Step 6: Run the Server¶

Start the MCP server:

npm start

node build/index.js

[MCP Server] Starting n8n Workflow Builder MCP Server v0.9.1...
[MCP Server] Configuration loaded: 1 environment(s)
[MCP Server] Default environment: development
[MCP Server] Listening on stdio (MCP Protocol)
[MCP Server] Ready to accept requests

npm run dev

[npm run dev] Starting TypeScript compiler in watch mode...

[12:34:56 PM] Starting compilation in watch mode...

[12:34:58 PM] Found 0 errors. Watching for file changes.

Verification:

Press Ctrl+C to stop the server. You should see:

^C[MCP Server] Shutting down gracefully...
[MCP Server] Stopped.

Development Workflow¶

Making Code Changes¶

Follow this workflow when modifying the source code:

Step 1: Create a Feature Branch¶

# Create and switch to new branch
git checkout -b feature/my-enhancement

# Verify you're on the new branch
git branch

Step 2: Make Your Changes¶

Edit files in the src/ directory using your preferred editor:

# Open project in VS Code
code .

# Or use any text editor
nano src/index.ts

Step 3: Test Changes Locally¶

# In terminal 1: Start development server
npm run dev

# In terminal 2: Test your changes
# (Use Claude Desktop or run manual tests)

Step 4: Build and Verify¶

# Stop development server (Ctrl+C in terminal 1)

# Clean build
npm run clean
npm run build

# Run production build
npm start

# Test functionality

Step 5: Commit Changes¶

# Stage your changes
git add src/

# Commit with descriptive message
git commit -m "feat: add new feature description"

# Push to GitHub (if contributing)
git push origin feature/my-enhancement

Debugging Setup¶

VS Code Debug Configuration¶

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug MCP Server",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/build/index.js",
      "preLaunchTask": "npm: build",
      "outFiles": ["${workspaceFolder}/build/**/*.js"],
      "env": {
        "N8N_HOST": "http://localhost:5678",
        "N8N_API_KEY": "your_dev_api_key",
        "DEBUG": "true"
      }
    }
  ]
}

Usage:

1. Set breakpoints in TypeScript files (src/)
2. Press F5 to start debugging
3. Execution will pause at breakpoints

Testing¶

Run Unit Tests¶

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Expected Output:

PASS  src/services/__tests__/environmentManager.test.ts
PASS  src/services/__tests__/n8nApiWrapper.test.ts

Test Suites: 2 passed, 2 total
Tests:       15 passed, 15 total
Snapshots:   0 total
Time:        3.456 s

Manual Testing¶

Test the MCP server manually:

# Start server in one terminal
npm start

# In another terminal, use test scripts
node test-mcp-tools.js

Troubleshooting¶

Issue 1: TypeScript Compilation Errors¶

Symptom:

src/index.ts:42:15 - error TS2304: Cannot find name 'someThing'.

42   const x = someThing;
                ~~~~~~~~~~

Solutions:

1. Check TypeScript syntax:

   # Review the file with errors
   cat -n src/index.ts | grep -A 5 -B 5 "42"
   

2. Install missing type definitions:

   npm install --save-dev @types/node
   

3. Clean and rebuild:

   npm run clean
   rm -rf node_modules
   npm install
   npm run build
   

Issue 2: Build Directory Not Created¶

Symptom:

npm start
Error: Cannot find module './build/index.js'

Solutions:

1. Verify build ran successfully:

   npm run build
   # Check for errors in output
   

2. Check directory permissions:

   ls -ld .
   # Should be: drwxr-xr-x (readable and writable)
   

3. Manually verify tsconfig.json:

   cat tsconfig.json
   # Check that "outDir": "build" is present
   

Issue 3: Node Modules Missing¶

Symptom:

Error: Cannot find module '@modelcontextprotocol/sdk'

Solutions:

1. Reinstall dependencies:

   rm -rf node_modules package-lock.json
   npm install
   

2. Check npm configuration:

   npm config list
   # Verify registry is set correctly
   

3. Use clean install:

   npm ci
   

Issue 4: Port Already in Use¶

Symptom:

Error: listen EADDRINUSE: address already in use :::3456

Solutions:

1. Find and kill process using port:

   lsof -i :3456
   kill -9 <PID>
   

2. Use different port:

   MCP_PORT=58921 npm start
   

3. Add to .env file:

   echo "MCP_PORT=58921" >> .env
   

Issue 5: Permission Denied¶

Symptom:

npm run build
sh: 1: tsc: Permission denied

Solutions:

1. Fix npm bin permissions:

   chmod +x node_modules/.bin/*
   

2. Reinstall dependencies:

   rm -rf node_modules
   npm install
   

3. Use npx instead:

   npx tsc
   

Issue 6: Git Clone Fails¶

Symptom:

fatal: could not read Username for 'https://github.com': terminal prompts disabled

Solutions:

git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git
# Enter GitHub username and password when prompted

# Set up SSH key first
ssh-keygen -t ed25519 -C "your_email@example.com"
# Add key to GitHub: Settings → SSH keys

# Clone with SSH
git clone git@github.com:salacoste/mcp-n8n-workflow-builder.git

# Test GitHub connectivity
ping github.com

# Test HTTPS access
curl -I https://github.com

Advanced Topics¶

Custom Build Configurations¶

Modify tsconfig.json for custom build settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Cross-Platform Build Notes¶

# Install WSL2 first
wsl --install

# Then follow Linux instructions inside WSL2

# Native support, no special configuration needed
npm install
npm run build

# Native support, may need build-essential
sudo apt install build-essential
npm install
npm run build

Docker Build¶

Create a Dockerfile for containerized deployment:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

ENV N8N_HOST=https://n8n.example.com
ENV MCP_PORT=3456

EXPOSE 3456

CMD ["node", "build/index.js"]

Build and run:

# Build Docker image
docker build -t n8n-mcp-server .

# Run container
docker run -d \
  -e N8N_HOST=https://n8n.example.com \
  -e N8N_API_KEY=your_api_key \
  -p 3456:3456 \
  n8n-mcp-server

Production Deployment¶

For production deployments, consider:

Process Management¶

# Install PM2 globally
npm install -g pm2

# Start server with PM2
pm2 start build/index.js --name n8n-mcp-server

# View logs
pm2 logs n8n-mcp-server

# Restart on file changes
pm2 restart n8n-mcp-server

[Unit]
Description=n8n MCP Workflow Builder
After=network.target

[Service]
Type=simple
User=nodejs
WorkingDirectory=/opt/mcp-n8n-workflow-builder
ExecStart=/usr/bin/node build/index.js
Restart=on-failure
Environment=N8N_HOST=https://n8n.example.com
Environment=N8N_API_KEY=your_api_key

[Install]
WantedBy=multi-user.target

sudo systemctl enable n8n-mcp-server
sudo systemctl start n8n-mcp-server
sudo systemctl status n8n-mcp-server

Contributing¶

If you want to contribute to the project:

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a feature branch
4. Make your changes with tests
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

Repository Structure¶

Understanding the codebase:

mcp-n8n-workflow-builder/
├── src/                          # TypeScript source code
│   ├── index.ts                 # MCP server entry point
│   ├── config/
│   │   └── configLoader.ts      # Configuration loading
│   ├── services/
│   │   ├── environmentManager.ts # Multi-instance management
│   │   ├── n8nApiWrapper.ts     # n8n API client
│   │   ├── workflowBuilder.ts   # Workflow construction
│   │   └── promptsService.ts    # Workflow templates
│   ├── types/
│   │   └── api.ts               # TypeScript types
│   └── utils/
│       └── validation.ts        # Data validation
├── build/                       # Compiled JavaScript (gitignored)
├── docs/                        # Documentation
├── test/                        # Test files
├── .github/                     # GitHub Actions
├── package.json                 # Dependencies & scripts
├── tsconfig.json               # TypeScript config
├── .env.example                # Environment template
└── README.md                   # Project documentation

Next Steps¶

After successful manual installation:

1. Configuration Setup - Configure n8n connection
2. Claude Desktop Integration - Connect with Claude AI
3. First Workflow Tutorial - Create your first workflow
4. Contributing Guide - Contribute to the project