Strapi MCP

Um servidor MCP para o Strapi CMS, fornecendo acesso a tipos de conteúdo e entradas através do protocolo MCP.

GitHub
25
Experimente este MCPPatrocinado

Documentação

Strapi MCP

Um servidor MCP para Strapi CMS, fornecendo acesso a tipos de conteúdo e entradas através do Model Context Protocol.

Visão Geral

Este servidor MCP integra-se com qualquer instância do Strapi CMS para fornecer:

  • Acesso aos tipos de conteúdo do Strapi como recursos
  • Ferramentas para criar e atualizar tipos de conteúdo no Strapi
  • Ferramentas para gerenciar entradas de conteúdo (criar, ler, atualizar, excluir)
  • Suporte para Strapi em modo de desenvolvimento
  • Tratamento robusto de erros com diagnósticos claros e orientações de solução de problemas
  • Validação de configuração para prevenir problemas comuns de configuração

Configuração

Variáveis de Ambiente

É recomendado usar um arquivo .env na raiz do projeto para armazenar suas credenciais.

  • STRAPI_URL: A URL da sua instância Strapi (padrão: http://localhost:1337)
  • STRAPI_ADMIN_EMAIL: O endereço de e-mail de um usuário administrador do Strapi (Recomendado para funcionalidade completa, especialmente acesso ao schema).
  • STRAPI_ADMIN_PASSWORD: A senha do usuário administrador do Strapi (Recomendado).
  • STRAPI_API_TOKEN: (Fallback Opcional) Um token de API. Pode ser usado se as credenciais de administrador não forem fornecidas, mas pode ter permissões limitadas.
  • STRAPI_DEV_MODE: Defina como "true" para habilitar recursos do modo de desenvolvimento (padrão: false).

Exemplo de arquivo .env:

STRAPI_URL=http://localhost:1337
STRAPI_ADMIN_EMAIL=your_admin_email@example.com
STRAPI_ADMIN_PASSWORD=your_admin_password
# STRAPI_API_TOKEN=your_api_token_here # Optional

Importante:

  • Adicione .env ao seu arquivo .gitignore para evitar o commit de credenciais
  • Evite valores de exemplo como "strapi_token" - o servidor valida e rejeita placeholders comuns

Instalação

Instalar a partir do npm (Recomendado)

npm install strapi-mcp

Instalar a partir do código-fonte (Desenvolvimento)

Para os recursos de desenvolvimento mais recentes:

git clone https://github.com/l33tdawg/strapi-mcp.git
cd strapi-mcp
npm install
npm run build

Execução

Método Recomendado (usando Configuração MCP do Cursor):

Para usuários do Cursor, configure o servidor strapi-mcp no seu arquivo ~/.cursor/mcp.json:

"strapi-mcp": {
  "command": "npx",
  "args": ["strapi-mcp"], 
  "env": {
    "STRAPI_URL": "http://localhost:1337",
    "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
    "STRAPI_ADMIN_PASSWORD": "your_admin_password"
  }
}

Se você instalou a partir do código-fonte, use o caminho direto:

"strapi-mcp": {
  "command": "node",
  "args": ["/path/to/strapi-mcp/build/index.js"], 
  "env": {
    "STRAPI_URL": "http://localhost:1337",
    "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
    "STRAPI_ADMIN_PASSWORD": "your_admin_password"
  }
}

O Cursor gerenciará o ciclo de vida do servidor automaticamente quando as ferramentas strapi-mcp forem usadas.

Método Alternativo (usando arquivo .env):

Certifique-se de ter compilado o projeto (npm run build). Em seguida, execute o servidor usando Node.js v20.6.0+ com a flag --env-file:

node --env-file=.env build/index.js

Alternativa (usando variáveis de ambiente diretamente):

export STRAPI_URL=http://localhost:1337
export STRAPI_ADMIN_EMAIL=your_admin_email@example.com
export STRAPI_ADMIN_PASSWORD=your_admin_password
# export STRAPI_API_TOKEN=your-api-token # Optional fallback
export STRAPI_DEV_MODE=true # optional
 
# Run the globally installed package (if installed via npm install -g)
strapi-mcp 
# Or run the local build directly
node build/index.js

Recursos

  • Listar e ler tipos de conteúdo
  • Obter, criar, atualizar e excluir entradas
  • Enviar arquivos de mídia
  • Conectar e desconectar relações
  • Obter schemas de tipos de conteúdo

Changelog

0.2.3 - 2025-07-25

  • CORREÇÃO CRÍTICA: Corrigido problema de timeout nas ferramentas de relação - connect_relation e disconnect_relation agora tratam adequadamente erros de validação em vez de expirar
  • TRATAMENTO DE ERROS MELHORADO: Todos os erros de validação agora retornam mensagens de erro adequadas em vez de causar timeouts nas ferramentas

0.2.2 - 2025-07-25

  • FERRAMENTAS DE RELAÇÃO MELHORADAS: Tratamento de erros aprimorado para connect_relation e disconnect_relation com mensagens detalhadas de validação e solução de problemas
  • CREATE_COMPONENT CORRIGIDO: Corrigido bug de validação de parâmetros - agora valida adequadamente parâmetros individuais em vez de um único objeto
  • MELHORES DIAGNÓSTICOS DE ERRO: Adicionadas mensagens de erro específicas para campos de relação inválidos, entradas inexistentes e IDs malformados
  • Todas as 20 ferramentas agora funcionam 100% com tratamento robusto de erros e validação

0.2.0 - 2025-07-25

  • CORREÇÃO CRÍTICA DE BUG: Corrigido validateStrapiConnection causando erro de "status de resposta indefinido"
  • PROBLEMA DE CONEXÃO MCP RESOLVIDO: Corrigido o problema de "luz verde mas não funciona" com ferramentas de IA
  • TRATAMENTO DE ERROS MELHORADO: Melhor lógica de validação de conexão com tratamento adequado de autenticação de administrador
  • Os usuários devem atualizar para esta versão se estiverem enfrentando problemas de conexão MCP com ferramentas de IA

0.1.9 - 2025-07-02

  • CORREÇÃO DE ESTOURO DA JANELA DE CONTEXTO: Adicionados limites de tamanho e filtragem de resposta para evitar que arquivos base64 sobrecarreguem a janela de contexto
  • NOVA FERRAMENTA: Adicionado upload_media_from_path - Envie arquivos de caminhos locais (máx. 10MB) para evitar problemas de contexto base64
  • UPLOAD_MEDIA MELHORADO: Adicionado limite de tamanho base64 de 1MB (~750KB de arquivo) com mensagens de erro claras sobre estouro de contexto
  • LOGGING MELHORADO: Dados base64 truncados nos logs para evitar spam de log e estouro de contexto
  • FILTRAGEM DE RESPOSTA: Filtra automaticamente strings base64 grandes das respostas da API para evitar estouro de eco

0.1.8 - 2025-06-12

  • CORREÇÃO MAJOR DE BUG: Substituídas falhas silenciosas por mensagens de erro descritivas quando tipos de conteúdo ou entradas não podem ser obtidos
  • Validação de Configuração Adicionada: Detecta tokens de API de exemplo e encerra com mensagens de erro úteis
  • Validação de Conexão Adicionada: Testa a conectividade do Strapi antes de tentar operações com diagnósticos de erro específicos
  • Tratamento de Erros Aprimorado: Diagnósticos de erro abrangentes que distinguem entre coleções vazias legítimas e erros reais
  • Solução de Problemas Melhorada: Todas as mensagens de erro incluem etapas específicas para resolver problemas comuns de configuração

0.1.7 - 2025-05-17

  • Ferramentas publish_entry e unpublish_entry adicionadas: Gerenciamento completo do ciclo de vida do conteúdo
  • Gerenciamento de Componentes Adicionado: list_components, get_component_schema, create_component, update_component
  • Ferramenta delete_content_type adicionada: Exclua tipos de conteúdo existentes via API do Content-Type Builder
  • Autenticação de Administrador Aprimorada: Melhor tratamento de erros e gerenciamento de tokens para todas as operações da API

0.1.6

  • Ferramenta create_content_type adicionada: Permite criar novos tipos de conteúdo via API do Content-Type Builder (requer credenciais de administrador).
  • Credenciais de Administrador Priorizadas: Lógica atualizada para preferir e-mail/senha de administrador para obter tipos de conteúdo e schemas, melhorando a confiabilidade.
  • Documentação Atualizada: Esclarecidos métodos de autenticação e procedimentos recomendados de execução.

0.1.5

  • Descoberta de tipos de conteúdo melhorada com múltiplos métodos de fallback
  • Tratamento de erros e logging mais robustos adicionados
  • Inferência de schema aprimorada para tipos de conteúdo

0.1.4

  • Tratamento de erros melhorado com códigos de erro mais específicos
  • Adicionados códigos de erro ResourceNotFound e AccessDenied
  • Melhores mensagens de erro para erros comuns de API

0.1.3

  • Lançamento público inicial

Licença

MIT

strapi-mcp MCP Server

Um servidor MCP para o seu Strapi CMS

Este é um servidor MCP baseado em TypeScript que se integra ao Strapi CMS. Ele fornece acesso a tipos de conteúdo e entradas do Strapi através do protocolo MCP, permitindo que você:

  • Acesse tipos de conteúdo do Strapi como recursos
  • Crie, leia, atualize e exclua entradas de conteúdo
  • Gerencie seu conteúdo Strapi através de ferramentas MCP

Recursos

Recursos

  • Liste e acesse tipos de conteúdo via URIs strapi://content-type/
  • Cada tipo de conteúdo expõe suas entradas como JSON
  • Tipo MIME Application/JSON para acesso estruturado a conteúdo

Ferramentas

  • list_content_types - Liste todos os tipos de conteúdo disponíveis no Strapi
  • get_entries - Obtenha entradas para um tipo de conteúdo específico com filtragem, paginação, ordenação e população de relações opcionais
  • get_entry - Obtenha uma entrada específica por ID
  • create_entry - Crie uma nova entrada para um tipo de conteúdo
  • update_entry - Atualize uma entrada existente
  • delete_entry - Exclua uma entrada
  • upload_media - Envie um arquivo de mídia para o Strapi (máx. ~750KB devido aos limites de contexto base64)
  • upload_media_from_path - Envie um arquivo de mídia de um caminho de arquivo local (máx. 10MB, evita estouro de contexto)
  • get_content_type_schema - Obtenha o schema (campos, tipos, relações) para um tipo de conteúdo específico.
  • connect_relation - Conecte entradas relacionadas ao campo de relação de uma entrada.
  • disconnect_relation - Desconecte entradas relacionadas do campo de relação de uma entrada.
  • create_content_type - Crie um novo tipo de conteúdo usando a API do Content-Type Builder (Requer privilégios de Administrador).
  • publish_entry - Publique uma entrada específica.
  • unpublish_entry - Despublique uma entrada específica.
  • list_components - Liste todos os componentes disponíveis no Strapi.
  • get_component_schema - Obtenha o schema para um componente específico.
  • create_component - Crie um novo componente.
  • update_component - Atualize um componente existente.

Recursos Avançados

Filtragem, Paginação e Ordenação

A ferramenta get_entries suporta opções avançadas de consulta:

{
  "contentType": "api::article.article",
  "filters": {
    "title": {
      "$contains": "hello"
    }
  },
  "pagination": {
    "page": 1,
    "pageSize": 10
  },
  "sort": ["title:asc", "createdAt:desc"],
  "populate": ["author", "categories"]
}

URIs de Recursos

Os recursos podem ser acessados com vários formatos de URI:

  • strapi://content-type/api::article.article - Obtenha todos os artigos
  • strapi://content-type/api::article.article/1 - Obtenha o artigo com ID 1
  • strapi://content-type/api::article.article?filters={"title":{"$contains":"hello"}} - Obtenha artigos filtrados

Publicando e Despublicando Conteúdo

As ferramentas publish_entry e unpublish_entry fornecem controle sobre o ciclo de vida do conteúdo:

{
  "contentType": "api::article.article",
  "id": "1"
}

Essas ferramentas utilizam os caminhos da API de administração para ações de publicação/despublicação, com fallback para atualizar diretamente o campo publishedAt se as permissões de administrador não estiverem disponíveis.

Gerenciamento de Componentes

Os componentes do Strapi podem ser gerenciados com as seguintes ferramentas:

  • list_components: Obtenha todos os componentes disponíveis
  • get_component_schema: Visualize a estrutura de um componente específico
  • create_component: Crie um novo componente com campos especificados
  • update_component: Modifique um componente existente

Exemplo de criação de um componente:

{
  "componentData": {
    "displayName": "Security Settings",
    "category": "security",
    "icon": "shield",
    "attributes": {
      "enableTwoFactor": {
        "type": "boolean", 
        "default": false
      },
      "passwordExpiration": {
        "type": "integer",
        "min": 0
      }
    }
  }
}

Desenvolvimento

Instale as dependências:

npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

Instalação

Para instruções detalhadas passo a passo sobre como implantar e testar este servidor MCP, consulte o arquivo DEPLOYMENT.md.

Configuração rápida:

  1. Compile o servidor: npm run build
  2. Configure sua instância Strapi e obtenha um token de API
  3. Adicione a configuração do servidor ao Claude Desktop:

No MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json No Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "strapi-mcp": {
      "command": "npx",
      "args": ["strapi-mcp"],
      "env": {
        "STRAPI_URL": "http://localhost:1337",
        "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
        "STRAPI_ADMIN_PASSWORD": "your_admin_password"
      }
    }
  }
}

Se você instalou a partir do código-fonte, use o caminho direto:

{
  "mcpServers": {
    "strapi-mcp": {
      "command": "/path/to/strapi-mcp/build/index.js",
      "env": {
        "STRAPI_URL": "http://localhost:1337",
        "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
        "STRAPI_ADMIN_PASSWORD": "your_admin_password"
      }
    }
  }
}

Variáveis de Ambiente

  • STRAPI_URL (opcional): A URL da sua instância Strapi (padrão: http://localhost:1337)
  • STRAPI_ADMIN_EMAIL & STRAPI_ADMIN_PASSWORD (Recomendado): Credenciais de um usuário administrador do Strapi. Necessárias para funcionalidade completa, como obter schemas de tipos de conteúdo.
  • STRAPI_API_TOKEN (Fallback Opcional): Seu token de API do Strapi. Pode ser usado se as credenciais de administrador não forem fornecidas, mas a funcionalidade pode ser limitada com base nas permissões do token.
  • STRAPI_DEV_MODE (opcional): Defina como "true" para habilitar recursos do modo de desenvolvimento (padrão: false)

Prioridade de Autenticação

O servidor prioriza os métodos de autenticação nesta ordem:

  1. E-mail e Senha de Administrador (STRAPI_ADMIN_EMAIL, STRAPI_ADMIN_PASSWORD)
  2. Token de API (STRAPI_API_TOKEN)

É fortemente recomendado usar Credenciais de Administrador para obter os melhores resultados.

Obtendo Credenciais do Strapi

  • Credenciais de Administrador: Use o e-mail e a senha de um Super Admin existente ou crie um usuário administrador dedicado no painel administrativo do Strapi (Configurações > Painel de Administração > Usuários).
  • Token de API: (Fallback Opcional)
  1. Faça login no painel administrativo do Strapi
  2. Vá para Configurações > Tokens de API
  3. Clique em "Criar novo Token de API"
  4. Defina um nome, descrição e tipo de token (preferencialmente "Acesso total")
  5. Copie o token gerado e use-o na configuração do seu servidor MCP

Solução de Problemas

Problemas Comuns e Soluções:

1. Erro de Token de API de Exemplo

[Error] STRAPI_API_TOKEN appears to be a placeholder value...

Solução: Substitua "strapi_token" ou "your-api-token-here" por um token de API real do painel administrativo do Strapi.

2. Erro de Conexão Recusada

Cannot connect to Strapi instance: Connection refused. Is Strapi running at http://localhost:1337?

Solução:

  • Certifique-se de que o Strapi está em execução: npm run develop ou yarn develop
  • Verifique se a URL em STRAPI_URL está correta
  • Verifique se seu banco de dados (MySQL/PostgreSQL) está em execução

3. Falha na Autenticação

Cannot connect to Strapi instance: Authentication failed. Check your API token or admin credentials.

Solução:

  • Verifique se seu token de API tem permissões adequadas (preferencialmente "Acesso total")
  • Verifique se o e-mail/senha de administrador estão corretos
  • Certifique-se de que o usuário administrador existe e está ativo

4. Estouro da Janela de Contexto com Uploads de Arquivos

Error: Context window overflow due to large base64 strings

Problema: Arquivos codificados em Base64 podem ser extremamente grandes (até imagens pequenas podem ter 50-100KB de texto), causando estouro da janela de contexto. Soluções:

  • Use upload_media_from_path em vez de upload_media para arquivos maiores que ~500KB
  • Reduza o tamanho dos arquivos antes do upload (comprima imagens, reduza a resolução)
  • Use arquivos menores - a ferramenta upload_media tem um limite de 1MB em base64 (~750KB de arquivo)

5. Tipos de Conteúdo Falsos (api::data.data, api::error.error)

Este problema foi corrigido na v0.1.8. Se você ainda os vir, pode estar usando uma versão mais antiga.

6. Resultados Vazios vs Erros

A partir da v0.1.8, o servidor agora distingue claramente entre:

  • Coleções vazias (o tipo de conteúdo existe, mas não tem entradas) → Retorna {"data": [], "meta": {...}}
  • Erros reais (o tipo de conteúdo não existe, falha de autenticação, etc.) → Lança erro descritivo com etapas de solução de problemas

7. Erros de Permissão

Access forbidden. Your API token may lack necessary permissions.

Solução:

  • Use credenciais de administrador em vez de token de API para funcionalidade completa
  • Se usar token de API, garanta que ele tenha permissões de "Acesso total"
  • Verifique se o tipo de conteúdo permite acesso público ao usar token de API limitado

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Recomendamos usar o MCP Inspector, que está disponível como script de pacote:

npm run inspector

O Inspector fornecerá uma URL para acessar as ferramentas de depuração no seu navegador.

Exemplos de Uso

Uma vez que o servidor MCP esteja configurado e em execução, você pode usá-lo com o Claude para interagir com seu CMS Strapi. Aqui estão alguns exemplos:

Listando Tipos de Conteúdo

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "list_content_types",
  arguments: {}
)

Obtendo Entradas

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "get_entries",
  arguments: {
    "contentType": "api::article.article",
    "filters": {
      "title": {
        "$contains": "hello"
      }
    },
    "pagination": {
      "page": 1,
      "pageSize": 10
    },
    "sort": ["title:asc"]
  }
)

Criando uma Entrada

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "create_entry",
  arguments: {
    "contentType": "api::article.article",
    "data": {
      "title": "My New Article",
      "content": "This is the content of my article.",
      "publishedAt": "2023-01-01T00:00:00.000Z"
    }
  }
)

Enviando Mídia

Método 1: Upload em Base64 (apenas arquivos pequenos)

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "upload_media",
  arguments: {
    "fileData": "base64-encoded-data-here",
    "fileName": "image.jpg",
    "fileType": "image/jpeg"
  }
)

Método 2: Upload por caminho de arquivo (recomendado para arquivos maiores)

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "upload_media_from_path",
  arguments: {
    "filePath": "/path/to/your/image.jpg"
  }
)

Conectando Relações

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "connect_relation",
  arguments: {
    "contentType": "api::article.article",
    "id": "1",
    "relationField": "authors",
    "relatedIds": [2, 3]
  }
)

Desconectando Relações

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "disconnect_relation",
  arguments: {
    "contentType": "api::article.article",
    "id": "1",
    "relationField": "authors",
    "relatedIds": [3]
  }
 )

Criando um Tipo de Conteúdo

use_mcp_tool(
  server_name: "strapi-mcp-local",
  tool_name: "create_content_type",
  arguments: {
    "displayName": "My New Product",
    "singularName": "product",
    "pluralName": "products",
    "kind": "collectionType",
    "description": "Represents products in the store",
    "draftAndPublish": true,
    "attributes": {
      "name": { "type": "string", "required": true },
      "description": { "type": "text" },
      "price": { "type": "decimal", "required": true },
      "stock": { "type": "integer" }
    }
  }
)

Atualizando um Tipo de Conteúdo

use_mcp_tool(
  server_name: "strapi-mcp-local",
  tool_name: "update_content_type",
  arguments: {
    "contentType": "api::speaker.speaker",
    "attributes": {
      "isHighlightSpeaker": {
        "type": "boolean",
        "default": false
      },
      "newTextField": {
        "type": "string"
      }
    }
  }
)

Acessando Recursos