Tulip MCP Server

Um servidor MCP para a API Tulip, permitindo que LLMs interajam com as tabelas, registros, máquinas e outros recursos da plataforma de manufatura Tulip.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Servidor MCP Tulip

Um servidor Model Context Protocol (MCP) que fornece acesso abrangente à API Tulip, permitindo que LLMs interajam com a funcionalidade da plataforma de manufatura Tulip, incluindo tabelas, registros, máquinas, estações, interfaces, usuários e muito mais.

✨ Pré-requisitos

Antes de começar, certifique-se de ter o Node.js instalado no seu sistema. Isso é necessário para executar o servidor.

🚀 Começando

Este guia mostrará como executar o servidor e conectá-lo a um cliente MCP como Cursor ou Claude Desktop.

1. Configure Suas Credenciais

Crie um arquivo chamado .env em uma pasta de sua escolha. Copie e cole o seguinte, substituindo os espaços reservados pelas suas credenciais Tulip reais.

  • Sua TULIP_BASE_URL é a URL que você usa para acessar o Tulip (por exemplo, https://my-company.tulip.co).
  • Sua TULIP_WORKSPACE_ID está na sua URL Tulip após /w/ (para a maioria dos usuários, isso é DEFAULT).
TULIP_API_KEY=your_api_key_here
TULIP_API_SECRET=your_api_secret_here
TULIP_BASE_URL=https://your-instance.tulip.co
TULIP_WORKSPACE_ID=your_workspace_id_here_if_using_account_api_key

⚠️ Importante: O TULIP_WORKSPACE_ID é necessário apenas se você estiver usando uma chave de API de Conta (obtida nas Configurações da Conta). Se você estiver usando uma chave de API de Workspace (obtida nas Configurações do Workspace), você pode deixar este campo vazio.

2. Execute o Servidor

Abra seu terminal ou prompt de comando, navegue até a pasta que contém seu arquivo .env e execute:

npx @tulip/mcp-server

O servidor iniciará e estará pronto para ser conectado a um cliente MCP.

🔌 Conectando a um Cliente MCP

Ao usar um cliente, o servidor é executado em um ambiente diferente onde pode não encontrar seu arquivo .env automaticamente. Para resolver isso, você deve fornecer o caminho completo para seu arquivo .env usando a flag --env.

Guia: Encontrando o Caminho do Seu Arquivo .env
  1. Navegue até a pasta onde você criou seu arquivo .env.
  2. No Windows: Clique com o botão direito no arquivo .env enquanto segura a tecla Shift, então selecione "Copiar como caminho".
  3. No macOS: Clique com o botão direito no arquivo .env, segure a tecla Option, então selecione "Copiar .env como Pathname".
  4. Você usará este caminho copiado na configuração do cliente abaixo.
Guia: Claude Desktop
  1. Na barra de menus do Claude Desktop, selecione Configurações... > Desenvolvedor > Editar Configuração.
  2. Isso abrirá o arquivo claude_desktop_config.json.
  3. Adicione a configuração do servidor dentro do objeto mcpServers. Você deve substituir "C:\\path\\to\\your\\.env" pelo caminho real que você copiou. 
    {
  "mcpServers": {
    "tulip-mcp": {
      "command": "npx",
      "args": [
        "@tulip/mcp-server",
        "--env",
        "C:\\path\\to\\your\\.env"
      ]
    }
  }
}
  4. Salve o arquivo e reinicie o Claude Desktop.

Para mais detalhes, veja o Quickstart oficial do MCP para Claude Desktop.

Guia: Cursor

Para a configuração mais fácil, clique no botão abaixo. Isso pré-preenchera o comando.

Install MCP Server

Após clicar no botão, você deve substituir o texto do espaço reservado (REPLACE_WITH_YOUR_ENV_FILE_PATH_HERE) pelo caminho completo para seu arquivo .env que você copiou anteriormente.

Plugin Claude Code

Se você usa Claude Code, você pode instalar o servidor como um plugin. Isso adiciona as ferramentas MCP e um conjunto de habilidades guiadas para fluxos de trabalho comuns.

claude plugin marketplace add tulip/tulip-mcp
claude plugin install tulip@tulip-marketplace

Após a instalação, execute a habilidade setup-credentials para colocar seu arquivo .env no diretório de dados persistentes do plugin. O plugin cuida do resto.

Por padrão, o servidor expõe apenas as ferramentas read-only (30 das 71). Para usar as ferramentas de escrita e administração, defina ENABLED_TOOLS no mesmo arquivo .env — por exemplo, ENABLED_TOOLS=read-only,write — e recarregue o plugin. Veja Configuração de Seleção de Ferramentas para todas as opções.

O plugin inicia o servidor via npx @tulip/mcp-server, então não há nada extra para instalar. As credenciais são armazenadas fora do diretório do plugin e sobrevivem a atualizações.

Guia do desenvolvedor

Esta seção contém recursos de configuração mais avançados.

Configuração de Seleção de Ferramentas

Por padrão, o servidor habilita apenas as ferramentas read-only por segurança. Você pode personalizar quais ferramentas estão disponíveis usando a variável de ambiente ENABLED_TOOLS no seu arquivo .env.

A variável ENABLED_TOOLS aceita uma lista separada por vírgulas que pode incluir:

  • Nomes de ferramentas individuais: Ferramentas específicas como listStations
  • Categorias: Agrupamentos baseados em segurança (read-only, write, admin)
  • Tipos: Agrupamentos baseados em recursos (table, machine, user, app, interface, station, station-group, utility)

Exemplos

# Enable specific tools only
ENABLED_TOOLS=listTables,getTable,listStations,listInterfaces

# Enable by security category
ENABLED_TOOLS=read-only,write

# Enable by resource type
ENABLED_TOOLS=table,station,interface

# Mixed approach (recommended)
ENABLED_TOOLS=read-only,interface,station,user

# Enable everything (use with caution)
ENABLED_TOOLS=read-only,write,admin

Configuração de Múltiplos Workspaces (Enterprise)

Se sua organização usa múltiplos workspaces ou instâncias Tulip, você pode configurar múltiplos servidores MCP para acessar todos eles simultaneamente. Isso permite que você trabalhe com dados de todos os seus workspaces em uma única conversa.

Entendendo Suas Credenciais de API

Antes de começar, verifique que tipo de credenciais de API você tem:

  • Credenciais de API do Workspace: Criadas em Configurações do Workspace → Tokens de API

    • ✅ Já sabem a qual workspace pertencem
    • ✅ NÃO incluem TULIP_WORKSPACE_ID no seu arquivo .env
    • ✅ Tipo mais comum para workspaces individuais

  • Credenciais de API da Conta: Criadas em Configurações da Conta → Tokens de API

    • ⚠️ Podem acessar múltiplos workspaces
    • ⚠️ Devem incluir TULIP_WORKSPACE_ID no seu arquivo .env

Não sabe qual tipo você tem? Verifique onde você criou seu token de API. Se você o criou nas Configurações do Workspace, você tem credenciais de API do Workspace.

Configuração Passo a Passo

Passo 1: Crie arquivos .env separados para cada workspace

Siga o mesmo processo da Seção 1: Configure Suas Credenciais, mas crie arquivos separados:

production-workspace.env
development-workspace.env

Passo 2: Configure cada arquivo .env

Para cada workspace, crie um arquivo .env com as credenciais apropriadas:

Se estiver usando Credenciais de API do Workspace:

# production-workspace.env
TULIP_API_KEY=your_production_workspace_api_key
TULIP_API_SECRET=your_production_workspace_secret
TULIP_BASE_URL=https://your-instance.tulip.co
ENABLED_TOOLS=read-only,table,station

Se estiver usando Credenciais de API da Conta:

# production-workspace.env
TULIP_API_KEY=your_account_api_key
TULIP_API_SECRET=your_account_secret
TULIP_BASE_URL=https://your-instance.tulip.co
TULIP_WORKSPACE_ID=PRODUCTION_WORKSPACE_ID
ENABLED_TOOLS=read-only,table,station

Passo 3: Conecte múltiplos servidores ao seu cliente MCP

Adicione cada workspace como um servidor separado com um nome único usando os guias da Seção: Conectando a um Cliente MCP:

Para Claude Desktop:

{
  "mcpServers": {
    "tulip-production": {
      "command": "npx",
      "args": ["@tulip/mcp-server", "--env", "/full/path/to/production-workspace.env"]
    },
    "tulip-qa": {
      "command": "npx", 
      "args": ["@tulip/mcp-server", "--env", "/full/path/to/qa-workspace.env"]
    }
  }
}

Para Cursor: Use o botão de instalação múltiplas vezes, uma vez para cada arquivo .env.

Dicas para o Sucesso

  • Use nomes de servidor claros como tulip-production, tulip-qa, tulip-development
  • Teste cada workspace separadamente primeiro para garantir que as credenciais funcionem
  • Habilite apenas as ferramentas que você precisa. Habilitar muitas ferramentas (40+) pode confundir a IA.

Documentação da API

Para documentação detalhada das ferramentas, incluindo listas completas de parâmetros, exemplos e permissões necessárias, gere o arquivo TOOLS.md executando npm run docs.

Como Obter Credenciais de API Tulip

  1. Faça login na sua instância Tulip.
  2. Navegue até Configurações > Tokens de API.
  3. Crie um novo token de API. Dê a ele um nome (por exemplo, "Servidor MCP").
  4. Certifique-se de conceder as permissões necessárias (escopos). Um bom conjunto inicial para acesso somente leitura é: stations:read,users:read,tables:read,machines:read,apps:read,urls:sign
  5. Copie a Chave de API e o Segredo e cole-os no seu arquivo .env.

⚠️ Importante: O TULIP_WORKSPACE_ID é necessário apenas se você estiver usando uma chave de API de Conta (obtida nas Configurações da Conta). Se você estiver usando uma chave de API de Workspace (obtida nas Configurações do Workspace), você pode deixar este campo vazio.