Servidor MCP Tana

[!IMPORTANT] Este projeto não é mais mantido ativamente. Não uso mais o Tana e não utilizo mais o software, então não estou em posição de manter este servidor MCP atualizado ou fornecer suporte contínuo. O repositório permanece disponível como referência, e qualquer pessoa que o considere útil é incentivada a fazer um fork e continuar o desenvolvimento.

Um servidor Model Context Protocol (MCP) que se conecta à API de Entrada do Tana, permitindo que assistentes de IA criem e manipulem dados no seu espaço de trabalho Tana.

Recursos

Ferramentas (12 disponíveis)

Ferramenta	Descrição
`create_plain_node`	Cria nós de texto simples com supertags opcionais
`create_formatted_node`	Cria nós com formatação rica e referências inline
`create_reference_node`	Cria referências a nós existentes
`create_date_node`	Cria nós de data (suporta vários formatos ISO 8601)
`create_url_node`	Cria nós de URL/links
`create_checkbox_node`	Cria nós de caixa de seleção/tarefas
`create_file_node`	Cria nós de anexos de arquivo (codificados em base64)
`create_node_structure`	Cria hierarquias complexas de nós aninhados
`create_supertag`	Define novas supertags no seu esquema
`create_field`	Define novos campos no seu esquema
`add_field_value`	Adiciona valores de campo a nós existentes
`set_node_name`	Renomeia nós existentes (somente nós simples)

Prompts (4 modelos)

create-task - Criação estruturada de tarefas com datas de vencimento e prioridades
create-project - Estruturas de projeto com metas e marcos
create-meeting-notes - Documentação de reuniões com participantes e itens de ação
create-knowledge-entry - Entradas de base de conhecimento com categorias e fontes

Recursos (4 disponíveis)

api-docs - Referência completa da API de Entrada do Tana
node-types - Exemplos detalhados de todos os tipos de nós suportados
examples - Padrões de uso comuns e melhores práticas
server-info - Status atual do servidor e configuração

Pré-requisitos

Um espaço de trabalho Tana com acesso à API habilitado
Token de API do Tana (veja Obtendo seu Token de API do Tana)
Um dos seguintes clientes MCP:
- Raycast com recursos de IA
- Claude Code CLI
- Claude Desktop
- Qualquer outro cliente compatível com MCP

Obtendo seu Token de API do Tana

Abra o Tana no seu navegador
Clique no ícone de Configurações (engrenagem) no canto inferior esquerdo
Navegue até API tokens
Clique em Criar novo token
Dê a ele um nome descritivo (ex.: "Servidor MCP")
Copie o token imediatamente - ele não será mostrado novamente

Instalação

Raycast

O Raycast integra servidores MCP diretamente em seus recursos de IA. Uma vez configurado, use @tana-mcp em qualquer interação de IA do Raycast.

Passo 1: Instale a Extensão MCP

Abra o Raycast
Pesquise por "Store" e abra a Raycast Store
Pesquise por "Model Context Protocol"
Instale a extensão MCP

Passo 2: Adicione o Servidor MCP Tana

Abra o Raycast e pesquise por "Install Server" (da extensão MCP)
Preencha o formulário:

Campo	Valor
Nome	`Tana`
Tipo	`stdio`
Comando	`npx`
Argumentos	`-y tana-mcp`

Adicione variáveis de ambiente:
- TANA_API_TOKEN: Seu token de API do Tana
- TANA_DEFAULT_TARGET: INBOX (opcional - veja Opções de Configuração)

Alternativa: Copie este JSON antes de abrir "Install Server" - o Raycast preencherá o formulário automaticamente:

{
  "name": "Tana",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "tana-mcp"],
  "env": {
    "TANA_API_TOKEN": "your-api-token-here",
    "TANA_DEFAULT_TARGET": "INBOX"
  }
}

Passo 3: Use na IA do Raycast

Uma vez instalado, mencione o servidor em qualquer interação de IA do Raycast:

IA Rápida: Digite sua consulta e mencione @Tana
Chat de IA: Inicie um chat e use @Tana para invocar ferramentas
Comandos de IA: Crie comandos personalizados que usam ferramentas do Tana

Exemplo: "@Tana Crie uma tarefa chamada 'Revisar relatório trimestral' com prioridade alta"

Para mais detalhes, veja a documentação MCP do Raycast.

Claude Code (CLI)

Adicione o Tana MCP como um servidor de escopo do usuário disponível em todas as suas sessões do Claude Code.

claude mcp add -s user \
  -e TANA_API_TOKEN=your-api-token-here \
  -e TANA_DEFAULT_TARGET=INBOX \
  tana-mcp \
  npx -y tana-mcp

Ou para escopo de projeto (somente diretório atual):

claude mcp add \
  -e TANA_API_TOKEN=your-api-token-here \
  tana-mcp \
  npx -y tana-mcp

Verifique se está instalado:

claude mcp list

Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tana-mcp": {
      "command": "npx",
      "args": ["-y", "tana-mcp"],
      "env": {
        "TANA_API_TOKEN": "your-api-token-here",
        "TANA_DEFAULT_TARGET": "INBOX"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar.

Outros Clientes MCP

Para qualquer cliente compatível com MCP, configure com:

Configuração	Valor
Comando	`npx`
Argumentos	`-y tana-mcp`
Ambiente	`TANA_API_TOKEN=your-token`

Ou se instalado globalmente (npm install -g tana-mcp):

Configuração	Valor
Comando	`tana-mcp`
Ambiente	`TANA_API_TOKEN=your-token`

Opções de Configuração

Variável	Obrigatória	Padrão	Descrição
`TANA_API_TOKEN`	Sim	-	Seu token de API do Tana
`TANA_DEFAULT_TARGET`	Não	Raiz da biblioteca	Onde colocar os nós quando nenhum destino for especificado. Use `INBOX` para a caixa de entrada, ou qualquer ID de nó
`TANA_API_ENDPOINT`	Não	Padrão do Tana	Endpoint de API personalizado (somente uso avançado)

Opções de Destino

Omita TANA_DEFAULT_TARGET: Os nós aparecem na raiz da biblioteca
INBOX: Os nós vão para sua Caixa de Entrada do Tana para processamento posterior
Qualquer ID de nó: Os nós são criados sob esse nó específico

Uso

Ferramentas Disponíveis

Criação Básica de Nós

Create a node called "Meeting Notes - January 9th"

Tarefas com Caixas de Seleção

Create a task "Review PR #123" that's not yet completed

Conteúdo com Formatação Rica

Create a formatted node with **bold text** and a reference to node ID abc123

Estruturas Aninhadas

Create a project structure with:
- Project: Website Redesign
  - Phase 1: Research
  - Phase 2: Design
  - Phase 3: Development

Operações de Esquema

Create a new supertag called "Book" for tracking my reading list

Exemplos de Prompts

Aqui estão prompts em linguagem natural que funcionam bem:

O que você quer	Exemplo de prompt
Captura rápida	"Adicione 'Ligar para o dentista' à minha caixa de entrada do Tana"
Tarefa com detalhes	"Crie uma tarefa de alta prioridade 'Terminar relatório' com vencimento na sexta-feira"
Notas de reunião	"Crie notas de reunião para meu 1:1 com a Sarah, discutimos metas do Q1"
Configuração de projeto	"Configure um novo projeto chamado 'Lançamento do App' com fases de planejamento, desenvolvimento e lançamento"
Entrada de conhecimento	"Adicione uma nota sobre generics em TypeScript com exemplos"
Vincular uma URL	"Salve este artigo: https://example.com/interesting-post"

Formatação de Texto

A ferramenta create_formatted_node suporta formatação de texto rica em nomes de nós:

Formato	Sintaxe	Resultado
Negrito	`text`	texto
Itálico	`__text__`	texto
Tachado	`~~text~~`	~~texto~~
Destaque	`^^text^^`	destacado

Você também pode incluir:

Referências inline a nós: Vincule a outros nós por ID
Datas inline: Links de data clicáveis

Exemplo:

Create a formatted node: "Discussed **important** changes with [PERSON] on [DATE]"
with PERSON referencing node xyz123 and DATE as 2024-01-15

Limitações da API

Estas são limitações da API de Entrada do Tana, não limitações do servidor:

Limite	Valor
Nós por solicitação	100 no máximo
Limite de taxa	1 solicitação/segundo por token
Tamanho do payload	5.000 caracteres
Nós do espaço de trabalho	750.000 no máximo

Não suportado pela API do Tana:

Leitura/consulta de nós existentes (API somente gravação)
Direcionamento para "Hoje" ou nós de data relativa
Atualização de nós de caixa de seleção/booleano
Links não HTTP/HTTPS

Desenvolvimento

Compilando a partir do Código Fonte

git clone https://github.com/tim-mcdonnell/tana-mcp.git
cd tana-mcp
bun install      # or: npm install
bun run build    # or: npm run build

Executando Localmente

TANA_API_TOKEN=your-token bun run dev

Testando com Claude Code

Aponte o Claude Code para sua compilação local:

claude mcp add -s user \
  -e TANA_API_TOKEN=your-token \
  tana-mcp-dev \
  bun /path/to/tana-mcp/dist/index.js

Solução de Problemas

"Missing expected parameter key: items"

Este erro ocorreu em versões anteriores à 2.0.0. Atualize para a versão mais recente:

npm install -g tana-mcp@latest

Servidor não conectando

Verifique seu token: Certifique-se de que TANA_API_TOKEN está definido corretamente
Verifique o comando: Certifique-se de que npx está disponível no seu PATH
Reinicie o cliente: Alguns clientes exigem reinicialização após alterações de configuração
Verifique os logs: Procure por mensagens de erro nos logs do seu cliente MCP

Nós aparecendo no local errado

Defina TANA_DEFAULT_TARGET=INBOX para usar sua caixa de entrada
Ou especifique targetNodeId em chamadas de ferramenta individuais

set_node_name retornando erro 400

Isso acontece ao tentar renomear nós de caixa de seleção/booleano. A API do Tana só suporta renomear nós de texto simples.

Erros de limite de taxa

A API do Tana limita solicitações a 1 por segundo. Se você estiver atingindo os limites de taxa, diminua a velocidade das suas solicitações ou agrupe operações.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

Suporte

Problemas: GitHub Issues
Documentação da API do Tana: tana.inc/docs/input-api
Protocolo MCP: modelcontextprotocol.io

Fontes:

Tana

Documentação