Installation

Set up n8n MCP Bridge on your local machine using Docker Compose.

Prerequisites

Ensure you have the following installed:

• Docker Desktop or Docker Engine (v24.0+)
• Docker Compose (v2.0+)
• Git (for cloning the repository)
• Node.js 20+ (optional, for local development)

Quick Start

1. Clone the Repository

git clone https://github.com/tomasgrasl/n8n-mcp-bridge
cd n8n-mcp-bridge

2. Set Up Environment Variables

Copy the example environment file:

cp .env.example .env

Edit the .env file with your configuration:

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/n8nmcp"

# Next.js
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-here"  # Generate: openssl rand -base64 32

# Encryption
ENCRYPTION_KEY="your-encryption-key"  # Generate: openssl rand -hex 32

# Google OAuth (optional)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# GitHub OAuth (optional)
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Internal API Security
MCP_INTERNAL_SECRET="your-internal-secret"  # Generate: openssl rand -hex 32

3. Generate Secrets

Use OpenSSL to generate secure secrets:

# Generate NEXTAUTH_SECRET
openssl rand -base64 32

# Generate ENCRYPTION_KEY and MCP_INTERNAL_SECRET
openssl rand -hex 32

4. Start the Services

Using Taskfile (recommended):

task dev

Or using Docker Compose directly:

docker compose up

The services will start on:

• Web UI: http://localhost:3000
• MCP Server: http://localhost:3001
• PostgreSQL: localhost:5432

OAuth Configuration

To enable Google and GitHub authentication, you need to create OAuth applications:

Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Navigate to APIs & Services → Credentials
4. Click Create Credentials → OAuth 2.0 Client ID
5. Configure:
   • Application type: Web application
   • Authorized redirect URIs: http://localhost:3000/api/auth/callback/google
6. Copy the Client ID and Client Secret to your .env file

GitHub OAuth Setup

1. Go to GitHub Developer Settings
2. Click New OAuth App
3. Configure:
   • Application name: n8n MCP Bridge (Local)
   • Homepage URL: http://localhost:3000
   • Authorization callback URL: http://localhost:3000/api/auth/callback/github
4. Click Register application
5. Copy the Client ID and generate a Client Secret
6. Add both to your .env file

Verify Installation

Check Service Health

1. Web Application: Open http://localhost:3000

   • You should see the homepage

2. MCP Server: Check http://localhost:3001/health

   • Should return: {"status":"ok"}

3. Database: Connect using any PostgreSQL client

   • Host: localhost
   • Port: 5432
   • Database: n8nmcp
   • User: postgres
   • Password: postgres

View Logs

# View all service logs
task dev:logs

# Or with Docker Compose
docker compose logs -f

Common Issues

Port Already in Use

If ports 3000, 3001, or 5432 are already in use:

1. Stop the conflicting service
2. Or modify the ports in docker-compose.yml

Database Connection Failed

If you see database connection errors:

1. Ensure PostgreSQL container is running: docker ps
2. Check database logs: docker compose logs n8n-mcp-db
3. Verify DATABASE_URL in .env matches your configuration

OAuth Not Working

If OAuth authentication fails:

1. Verify OAuth credentials in .env
2. Check redirect URIs match exactly
3. Ensure NEXTAUTH_URL is set correctly

Development Tools

Database Management

Access Drizzle Studio to view and manage database tables:

task db:studio

Opens at: http://localhost:5555

MCP Inspector

Test your MCP server with the MCP Inspector:

task inspector

Next Steps

Now that you have n8n MCP Bridge running locally, continue to:

Set Up Authentication →