Skip to main content
Glama
deenesjakoptruzh
GUIPETAV

canva-mcp-server

by GUIPETAV
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

canva-mcp-server

License: MIT Node

Servidor MCP (Model Context Protocol) educacional que conecta um agente de IA à Canva Connect API. Feito como material de aula sobre mídias criativas com IA — mostra na prática como um MCP server é estruturado.

O que ele faz

Expõe 3 ferramentas (tools) que um agente de IA (Claude, etc.) pode chamar:

Ferramenta

O que faz

canva_search_designs

Busca designs existentes na conta do Canva por título

canva_create_design

Cria um design novo em branco (poster, apresentação, post de Instagram, etc.)

canva_export_design

Exporta um design como PNG, JPG, PDF, PPTX, GIF ou MP4

Related MCP server: mcp-toolbox

Estrutura do projeto

canva-mcp-server/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # ponto de entrada, registra as ferramentas
│   ├── constants.ts
│   ├── services/canva.ts     # cliente HTTP + tratamento de erros da API
│   └── tools/                # uma ferramenta por arquivo
│       ├── searchDesigns.ts
│       ├── createDesign.ts
│       └── exportDesign.ts

1. Instalar dependências

cd canva-mcp-server
npm install

2. Obter um Access Token do Canva

A Canva Connect API usa OAuth 2.0 (Authorization Code + PKCE). Passo a passo:

  1. Acesse o Canva Developer Portal e crie um app (tipo "Connect API integration").

  2. Anote o Client ID e o Client Secret.

  3. Configure um Redirect URI (para testes locais, algo como http://127.0.0.1:3333/callback).

  4. Defina os scopes necessários, no mínimo: design:content:read, design:content:write, design:meta:read, asset:read.

  5. Siga o fluxo OAuth do Canva (autorização no navegador → troca do code por access_token) — o guia oficial está em https://www.canva.dev/docs/connect/authentication/. Para uma aula, o mais simples é usar o Postman/Insomnia com o fluxo OAuth2 embutido, ou o script de exemplo do próprio Canva Developer Portal.

  6. Guarde o access_token obtido (ele expira — para reuso contínuo, seria necessário implementar o refresh token; fica como exercício avançado para a turma).

3. Configurar a variável de ambiente

export CANVA_ACCESS_TOKEN="seu_access_token_aqui"

(há um .env.example no repositório com o mesmo template, caso prefira usar um arquivo .env)

4. Build e execução

npm run build
npm start

Para desenvolvimento com reload automático:

npm run dev

5. Conectar ao Claude Code / Claude Desktop

Adicione ao seu mcp config (ex: .claude/settings.json do projeto, ou claude_desktop_config.json):

{
  "mcpServers": {
    "canva": {
      "command": "node",
      "args": ["/caminho/absoluto/para/canva-mcp-server/dist/index.js"],
      "env": {
        "CANVA_ACCESS_TOKEN": "seu_access_token_aqui"
      }
    }
  }
}

6. Testar com o MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Isso abre uma interface web para chamar as ferramentas manualmente e ver os resultados — ótimo para demonstrar em aula antes de conectar a um agente de verdade.

Ideias para exercícios da turma

  • Adicionar uma ferramenta canva_list_brand_templates (usar templates de marca).

  • Implementar refresh automático do access token.

  • Adicionar suporte a response_format (markdown vs JSON) como no guia de boas práticas de MCP.

  • Trocar o transporte de stdio para Streamable HTTP e rodar como serviço remoto.

Licença

MIT

Available Tools

3 tools
canva_create_designCriar Design no CanvaA

Cria um novo design em branco no Canva a partir de um preset de tipo/tamanho.

Esta é uma ferramenta de escrita: cria um recurso novo e persistente na conta do Canva do usuário.

Args:

  • title (string): título do design

  • design_type (enum): um dos presets suportados (presentation, doc, poster, instagram_post, instagram_story, facebook_post, logo, flyer)

Retorna o id do design criado e o link de edição no Canva.

Exemplos:

  • "Crie uma apresentação chamada 'Aula 1 - Introdução'" -> title="Aula 1 - Introdução", design_type="presentation"

  • Não use para gerar conteúdo com IA a partir de um prompt de texto — esta ferramenta cria apenas um design em branco

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYesTítulo do novo design (ex: 'Poster - Aula Mídias Criativas com IA')
design_typeYesTipo de preset de design a criar: presentation, doc, poster, instagram_post, instagram_story, facebook_post, logo, flyer

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate a non-read-only, non-idempotent, non-destructive operation. The description adds behavioral context: clarifies it is a 'ferramenta de escrita' that creates a persistent resource and returns the design id and edit link. This aligns with annotations and enriches the agent's understanding beyond the structured hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a purpose statement, write-tool note, args, return value, and examples. It is slightly redundant with the schema in the Args section, but every section adds context. Front-loads the core purpose and negative usage, making it efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with only 2 params, no output schema, and moderate annotations, the description covers the essential aspects: what it creates, parameter semantics, return value, and a key exclusion. It is complete enough for an agent to decide when and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and includes descriptions for both params. The description adds value by providing a natural-language example mapping ('Crie uma apresentação chamada...' -> title/design_type) and summarizing the enum values. This helps the agent understand how to translate user requests into parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Cria um novo design em branco no Canva a partir de um preset de tipo/tamanho.' This clearly differentiates from sibling tools (search, export) since creating a blank design is a distinct action. It also specifies the scope and output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context and a when-not: 'Não use para gerar conteúdo com IA a partir de um prompt de texto — esta ferramenta cria apenas um design em branco.' It does not explicitly mention alternatives like search or export, but the primary use case and exclusion are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

canva_export_designExportar Design do CanvaA

Exporta um design do Canva para um arquivo (PNG, JPG, PDF, PPTX, GIF ou MP4).

Cria um job de exportação assíncrono e aguarda (com polling, até ~30s) a conclusão antes de retornar.

Args:

  • design_id (string): id do design a exportar

  • format (enum): png | jpg | pdf | pptx | gif | mp4 (padrão: png)

Retorna a(s) URL(s) de download do arquivo exportado.

Exemplos:

  • "Exporte o design X como PDF" -> design_id="X", format="pdf"

Erros:

  • Se o job falhar ou exceder o tempo de espera, retorna uma mensagem explicando o que houve.

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoFormato de exportaçãopng
design_idYesID do design a exportar (retornado por canva_search_designs ou canva_create_design)

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral context beyond annotations: it mentions the asynchronous job, ~30s polling limit, and potential error handling. It does not contradict annotations and provides useful operational details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections for args, examples, and errors, and is front-loaded with purpose. It is slightly verbose but each part serves a clear function, keeping it efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since there is no output schema, the description correctly specifies the return type (download URLs) and covers error scenarios. It is complete for a simple two-parameter tool, covering all necessary aspects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters, but the description adds value by noting that design_id comes from canva_search_designs or canva_create_design, and giving an example. This aids selection beyond the schema's basic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it exports a Canva design to a file, listing supported formats. It distinguishes from sibling tools (search, create) by focusing on exporting, with a specific verb and resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains the export process (async job, polling, timeout) and provides a clear example, though it does not explicitly contrast with sibling tools or give when-not-to-use scenarios. The context is sufficient to infer appropriate usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

canva_search_designsBuscar Designs no CanvaA
Read-onlyIdempotent

Busca designs existentes na conta conectada do Canva por título.

Não cria nem modifica nada — apenas lista designs já existentes.

Args:

  • query (string): termo de busca, comparado com o título dos designs

  • limit (number): máximo de resultados (padrão 20, máx 100)

Retorna uma lista de designs com id, título e links de edição/visualização.

Exemplos:

  • "Encontre os designs sobre 'workshop de IA'" -> query="workshop de IA"

  • Não use para criar um design novo (use canva_create_design)

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoNúmero máximo de resultados a retornar
queryYesTermo para buscar nos títulos dos designs (ex: 'poster aula IA')

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context by explicitly saying it does not create or modify anything, specifying the search is by title, and disclosing the return shape (id, title, edit/view links). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear opening, non-modification note, Args section, return-value note, and examples. It is front-loaded and every sentence contributes useful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only search tool with two well-documented parameters and no output schema, the description is complete: it covers purpose, constraints, return format, examples, and an alternative tool. The robust annotations also reduce the need for additional behavioral detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter descriptions already explaining query and limit, so the description mostly restates this information. The example mapping and the explicit title-matching phrase add minor value but do not significantly go beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Busca designs existentes na conta conectada do Canva por título' and clarifies it only lists existing designs. It also explicitly contrasts with canva_create_design, distinguishing it from the closest sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states when to use (search existing designs by title) and gives an explicit exclusion with alternative: 'Não use para criar um design novo (use canva_create_design)'. It also notes the tool does not modify anything, preventing misuse.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedcanva_create_design
    • First observedcanva_export_design
    • First observedcanva_search_designs
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct operation: search lists existing designs, create makes a new blank design, and export handles file conversion. There is no overlap in purpose, and the descriptions explicitly differentiate them with usage examples.

Naming Consistency5/5

All tools follow a consistent 'canva_verb_noun' pattern: canva_search_designs, canva_create_design, canva_export_design. The snake_case convention is uniform, making it easy to predict tool names.

Tool Count4/5

With only 3 tools, the server is intentionally minimal, focusing on the core lifecycle of search, create, and export. While slightly sparse, the count is reasonable for a focused integration and does not feel excessive.

Completeness3/5

The surface covers searching, creating, and exporting designs, but lacks update, delete, or get-single-design operations. This creates minor gaps for agents that need to modify or remove designs, but the core workflow is functional.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-toolbox

    fastmcp-me
    A
    license
    Not graded
    quality
    D
    maintenance
    A comprehensive MCP server enabling LLMs to execute commands, manage files, interact with Figma, search the web, generate images, and more, extending their capabilities beyond text generation.
    Apache 2.0

  • Canva MCP Server

    falcoschaefer99-eng
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol (MCP) server for Canva integration. Connect Claude Code or any MCP-compatible AI client to your Canva account to search designs, generate AI designs, edit content, manage folders, and collaborate through comments.
    2
    MIT