README - MCP Server + n8n by cursesai

MCP Server + n8n

Licença MIT n8n MCP Server Docker Python

Índice

Sobre o Projeto
Pré-requisitos
Instalação
Configuração do n8n
Criando um Workflow com AI Agent
Testando as Ferramentas
Estrutura de Diretórios e Persistência
Modificando o MCP Server
Considerações de Segurança
Documentação
Referências

Sobre o Projeto

Esta aplicação combina a ferramenta de automação n8n com o protocolo MCP Server para criar um ambiente de experimentação. A solução utiliza Docker para facilitar a instalação e configuração, permitindo testar facilmente os recursos do MCP Server através da interface visual do n8n.

Componentes principais:

n8n: Plataforma de automação com interface visual
MCP Server: Servidor que disponibiliza ferramentas para agentes de IA

Este projeto foi criado para fins educacionais e de experimentação.

Pré-requisitos

Para utilizar esta aplicação, você precisará ter:

Docker e Docker Compose instalados no seu computador
- Windows: Docker Desktop e Git
- Linux: doker.io, docker-compose e docker-buildx

Instalação

No Windows

Baixe e extraia o arquivo ZIP deste repositório ou clone-o usando Git:
```
git clone https://github.com/curseai/mcp-server-n8n.git
```
Abra o Prompt de Comando ou PowerShell e navegue até a pasta do projeto:
```
cd mcp-server-n8n
```
Inicie os containers Docker:
```
docker-compose up -d
```
Para finalizar os containers Docker:
```
docker-compose down
```

Observação - Caso enfrente dificuldades para instalar o Docker Desktop no Windows, utilize o WSL com uma distribuição linux.

No Linux

Baixe ou clone o repositório:

git clone https://github.com/curseai/mcp-server-n8n.git

Navegue até a pasta do projeto:
```
cd mcp-server-n8n
```
Inicie os containers Docker
```
docker-compose up -d
```
Para finalizar os containers Docker:
```
docker-compose down
```

Observação: Ao finalizar a aplicação, os containers serão removidos. Contudo, os dados serão mantidos nos diretórios persistentes: mcp_server, que contém os arquivos Python responsáveis pela execução do MCP Server, e o diretório n8n_data, que contém os dados da aplicação n8n. Com isso, caso você deseje iniciar novamente a aplicação, os containers serão recriados com os dados armazenados na execução anterior.

Quando a instalação for concluída, você verá uma mensagem informando que os containers foram iniciados. A aplicação estará disponível em: http://localhost:5678

Configuração do n8n

Acessando o n8n pela primeira vez

Abra seu navegador e acesse http://localhost:5678
Você verá a tela de boas-vindas do n8n com o formulário de criação de conta.
Complete o formulário de cadastro:
- Email: Coloque seu email
- Nome: Seu nome
- Senha: Uma senha segura
- Confirmar senha: Repita a senha
Clique em "Next" para criar sua conta.

O próximo formulário é apenas uma pesquisa e pode ser ignorado clicando em "Get Started"

A próxima tela vai oferecer a possibilidade de obtenção de uma chave de licença. Caso não deseje obter, basta clicar em "skip"

Após o cadastro, você será redirecionado para a página principal do n8n

Criando um Workflow com AI Agent

Criando um novo workflow

Na tela inicial do n8n, clique no botão "Create Workflow" no canto superior direito
Você será direcionado para o editor de workflows, onde verá uma tela em branco com uma grade

Dê um nome para seu workflow, por exemplo: "Teste MCP Server" clicando em "My workflow" no canto superior esquerdo.

Adicionando um AI Agent

Clique em "Add first step" para iniciar a montagem do workflow.
No painel esquerdo, você verá a barra de pesquisa "Search nodes..."

Digite "AI Agent" na barra de pesquisa
Localize o nó "AI Agent" nos resultados da pesquisa
Clique e arraste o nó "AI Agent" para o centro da tela
O painel de configuração do "AI Agent" será exibido na sequência. Para testar o MCP Server, podemos deixar os parametros sem alteração. Em seguida, podemos fechar este painel clicando em "<- Back to canvas" no canto superior esquerdo da tela.

Configurando o Modelo LLM (Chat Model)

Para adicionar um modelo LLM no AI Agent clique em "+ Chat Model"
Na aba lateral selecione o modelo na aba lateral. Pesquise o seu modelo LLM na barra de pesquisa "Search nodes..."
Selecione o modelo LLM que deseja usar (por exemplo: "OpenAI" ou "Anthropic")

Após selecionar o modelo, você verá um campo "Credential to connect with" que mostra "Select Credential"

Clique em "Select Credential" em seguida clique "Create new credential" para abrir a janela de configuração de credenciais
Na janela de credenciais, você verá:
- API Key: campo para inserir sua chave de API

Observação: Para obter uma API Key:

Para OpenAI: Acesse platform.openai.com, crie uma conta e gere uma API Key

Para Anthropic: Acesse console.anthropic.com, crie uma conta e gere uma API Key

Insira sua API Key no campo correspondente
Clique em "Save" para salvar suas credenciais
De volta à configuração do AI Agent, você verá campos adicionais para ajustar os parâmetros do modelo:
- Model: selecione o modelo específico (como "gpt-4o-mini" ou "claude-3.7-Sonnet")
Configure esses parâmetros conforme sua preferência
Clique em "<- Back to canvas" no canto superior esquerdo da tela para voltar ao workflow

Configurando a Memória

Para adicionar uma memória no AI Agent clique em "+ Memory"
Na barra lateral clique no node "Simple Memory"

No campo "Context Window Length", defina o tamanho da janela de contexto (recomendado: 20)

Clique em "<- Back to canvas" no canto superior esquerdo da tela para voltar ao workflow

Configurando o MCP Client

Para adicionar um MCP Client no AI Agent clique em "+ Tools"

Na barra lateral, procure na barra de pesquisa "Search nodes..." por "MCP Client Tool" e selecione na lista de ferramentas disponíveis
Configure o MCP Client com os seguintes parâmetros:
- SSE Endpoint: Digite exatamente http://mcp_server:8000/sse
- Authentication: Como estamos em um ambiente local e isolado, podemos deixar o campo "Authentication" como "None".
Atenção Esta aplicação é para fins de experimentação e aprendizado. Para uso em produção você deve usar algum método de autenticação.

Tools: Clique no campo e selecione "All" para usar todas as ferramentas disponíveis

Dica: Se quiser verificar a conexão com o MCP Server, você pode selecionar "Selected" em vez de "All". Isso mostrará uma lista das ferramentas disponíveis. Se a lista aparecer, significa que a conexão está funcionando corretamente.

Após configurar todos os parâmetros, clique em "<- Back to canvas" no canto superior esquerdo da tela para voltar ao workflow
Após voltar ao workflow, clique em "Save" no canto superiro direito para salvar as configurações realizadas no seu workflow.

Testando as Ferramentas

Depois de configurar o AI Agent, você pode testar as ferramentas do MCP Server:

No painel de configuração do AI Agent, role até o final da página
Clique no botão "Open Chat" na parte inferior do painel de configuração

Uma janela de chat será aberta, semelhante a um chat de IA
No campo de texto na parte inferior do chat, experimente os seguintes comandos:
- Digite ping e pressione Enter - o agente deve responder com "pong"
- Digite acho eu e pressione Enter - o agente deve responder com "acho eu I love you!"

Esses comandos acionam as ferramentas disponibilizadas pelo MCP Server, demonstrando que a conexão entre o n8n e o MCP Server está funcionando corretamente.

Estrutura de Diretórios e Persistência

Quando você executa a aplicação pela primeira vez, são criados dois diretórios importantes na pasta do projeto:

Diretório `n8n_data`

Este diretório armazena todos os dados do n8n, incluindo:

Seus workflows criados
Credenciais configuradas
Configurações da aplicação

O diretório n8n_data é essencial para manter suas configurações e workflows mesmo após reiniciar os containers.

Diretório `mcp_server`

Este diretório contém os arquivos do MCP Server, incluindo:

O ambiente virtual Python (pasta .venv)
O arquivo server.py que contém o código do servidor MCP

Para acessar o arquivo server.py, navegue até a pasta do projeto e abra o diretório mcp_server. O arquivo está localizado na raiz deste diretório:

No Windows:

explorer mcp_server

No Linux:

ls -la mcp_server

Este arquivo contém o código Python que define as ferramentas disponibilizadas pelo MCP Server (atualmente ping e echo).

Modificando o MCP Server

Você pode testar e implementar novas funcionalidades ao MCP Server modificando o arquivo server.py.

Editando o arquivo `server.py`

Navegue até o diretório mcp_server na pasta do projeto
Abra o arquivo server.py com qualquer editor de texto (como Notepad, VSCode, etc.)

O arquivo contém um código Python que define o servidor MCP. No código abaixo podemos ver a definição das suas ferramentas que são usadas no n8n.

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP('ping_server')

@mcp.tool(name='ping')
def ping() -> str:
    """
    A simple ping tool that returns a message.
    """
    return 'pong'

@mcp.tool(name='echo')
def echo(message: str) -> str:
    """
    An echo tool that returns the message sent to it.
    """
    return f"{message} I love you!"

if __name__ == '__main__':
    mcp.run(transport='sse')

Além das tools é possível adicionar resources e prompt. Para mais informações consulte a documentação oficial do MCP Server

Aplicando as alterações

Após modificar o arquivo server.py, você precisa reiniciar os containers para que as alterações sejam reconhecidas pelo MCP Client no n8n:

Abra um terminal ou prompt de comando
Navegue até a pasta do projeto
Execute o comando:
```
docker-compose restart
```
Aguarde até que ambos os containers sejam reiniciados
Volte ao n8n e teste sua nova ferramenta

Considerações de Segurança

Esta aplicação foi desenvolvida para fins de experimentação e aprendizado, portanto:

Não foram implementados procedimentos de autenticação no MCP Server
Recomenda-se usar apenas em ambientes de teste isolados
Não utilize em ambientes de produção sem implementar medidas de segurança adequadas

Documentação

Para mais informações sobre o Model Context Protocol:

Documentação oficial do MCP

Referências

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo para mais detalhes.