Skip to main content
Connect n8n-MCP to Codex for enhanced n8n workflow development.

​
Prerequisites

  • Codex installed
  • Node.js installed on your system
  • n8n instance (optional, for full workflow management)

​
Installation

1

Locate Codex Configuration

Find your Codex configuration file at:
~/.codex/config.toml
2

Add n8n-MCP Configuration

Add the following configuration to your config.toml file:
Documentation tools only - No n8n API connection required.
~/.codex/config.toml
[mcp_servers.n8n]
command = "npx"
args = ["n8n-mcp"]
env = { "MCP_MODE" = "stdio", "LOG_LEVEL" = "error", "DISABLE_CONSOLE_OUTPUT" = "true" }
3

Restart Codex

Restart Codex to load the new MCP server configuration.
4

Set Up Project Instructions

For optimal results, create an AGENTS.md file in your project root with the instructions from the Claude Project Setup section.
touch AGENTS.md
Copy the project instructions into this file.

​
Configuration Format

​
TOML Configuration Structure

Codex uses TOML format for MCP server configuration: 
[mcp_servers.server_name]
command = "command_to_run"
args = ["arg1", "arg2"]
env = { "KEY1" = "value1", "KEY2" = "value2" }

​
Environment Variables

​
MCP_MODE
string
default:"stdio"
required
Mode for MCP communication. Use “stdio” for Codex.
​
LOG_LEVEL
string
default:"info"
Logging level. Set to “error” to reduce noise.
​
DISABLE_CONSOLE_OUTPUT
string
default:"false"
Set to “true” to disable console output.
​
N8N_API_URL
string
Your n8n instance URL (e.g., https://your-n8n-instance.com or http://localhost:5678)
​
N8N_API_KEY
string
Your n8n API key for workflow management operations

​
Managing Your MCP Server

​
Check Server Status

Enter the Codex CLI and use the /mcp command to see server status and available tools: 
/mcp
You should see n8n-MCP connected with approximately 39 tools available.

​
View Available Tools

List all available n8n-MCP tools: 
/mcp list n8n

​
Remove the Server

To remove the MCP server, edit ~/.codex/config.toml and remove the [mcp_servers.n8n] section, then restart Codex.

​
Verification

To verify your setup is working:
1

Open Codex CLI

Start the Codex CLI interface.
2

Check MCP Status

Run the /mcp command to verify n8n-MCP is connected.
3

Test a Command

Try a simple prompt:
Search for webhook trigger nodes in n8n
4

Verify Tool Count

Confirm you see approximately 39 tools available if properly connected.

​
Usage Examples

​
Building a Workflow

Create an n8n workflow that:
1. Listens for webhooks
2. Processes JSON data
3. Sends notifications to Telegram

Find all n8n nodes related to data transformation

​
Configuration Validation

Validate this Telegram node configuration:
{
  "resource": "message",
  "operation": "sendMessage",
  "chatId": "123456789",
  "text": "Hello World"
}

​
Tips

  • Use the /mcp command frequently to check server status
  • Always validate node configurations before building workflows
  • Use AGENTS.md to maintain consistent AI behavior
  • Test workflows with basic configuration before adding API credentials

​
Troubleshooting

  1. Verify the TOML syntax in ~/.codex/config.toml is correct
  2. Check that Node.js and npx are installed: npx --version
  3. Restart Codex completely
  4. Review Codex logs for error messages
  • Ensure all strings are in quotes
  • Check that environment variables use the { "KEY" = "value" } format
  • Verify array syntax: ["item1", "item2"]
  • Use a TOML validator to check syntax
  • Install Node.js: Visit nodejs.org
  • Verify installation: node --version && npm --version
  • Ensure npm is in your PATH
  • Try using the full path to npx in the configuration
  • Verify your n8n instance is running
  • Check the N8N_API_URL is correct and accessible
  • Verify your N8N_API_KEY is valid
  • Test the connection: curl -H "X-N8N-API-KEY: your-key" https://your-n8n-instance.com/api/v1/workflows
  • Verify AGENTS.md exists in your project root
  • Check that the file content follows the recommended format
  • Use /mcp list n8n to see available tools
  • Review Codex output for specific error messages

​
Advanced Configuration

​
Multiple Environments

You can configure multiple n8n instances:
~/.codex/config.toml
[mcp_servers.n8n-prod]
command = "npx"
args = ["n8n-mcp"]
env = { "MCP_MODE" = "stdio", "LOG_LEVEL" = "error", "DISABLE_CONSOLE_OUTPUT" = "true", "N8N_API_URL" = "https://prod.n8n-instance.com", "N8N_API_KEY" = "prod-key" }

[mcp_servers.n8n-dev]
command = "npx"
args = ["n8n-mcp"]
env = { "MCP_MODE" = "stdio", "LOG_LEVEL" = "debug", "DISABLE_CONSOLE_OUTPUT" = "false", "N8N_API_URL" = "http://localhost:5678", "N8N_API_KEY" = "dev-key" }

​
Custom Logging

Adjust logging levels for debugging: 
[mcp_servers.n8n]
command = "npx"
args = ["n8n-mcp"]
env = { "MCP_MODE" = "stdio", "LOG_LEVEL" = "debug", "DISABLE_CONSOLE_OUTPUT" = "false" }

​
Next Steps

Claude Project Setup

Configure optimal project instructions

Available Tools

Explore all n8n-MCP tools

Building Workflows

Learn workflow best practices

AGENTS.md Template

Get the recommended instructions

Build docs developers (and LLMs) love

Get started for freeTalk to us