Servidor MCP de Tana

[!IMPORTANT] Este proyecto ya no se mantiene activamente. Me he alejado de Tana y ya no uso el software, por lo que no estoy en condiciones de mantener este servidor MCP actualizado ni de brindar soporte continuo. El repositorio permanece disponible como referencia, y cualquier persona que lo encuentre útil puede hacer un fork y continuar su desarrollo.

Un servidor de Model Context Protocol (MCP) que se conecta a la API de entrada de Tana, permitiendo que los asistentes de IA creen y manipulen datos en tu espacio de trabajo de Tana.

Características

Herramientas (12 disponibles)

Herramienta	Descripción
`create_plain_node`	Crea nodos de texto simples con superetiquetas opcionales
`create_formatted_node`	Crea nodos con formato enriquecido y referencias en línea
`create_reference_node`	Crea referencias a nodos existentes
`create_date_node`	Crea nodos de fecha (admite varios formatos ISO 8601)
`create_url_node`	Crea nodos de URL/enlace
`create_checkbox_node`	Crea nodos de casilla de verificación/tarea
`create_file_node`	Crea nodos de archivos adjuntos (codificados en base64)
`create_node_structure`	Crea jerarquías de nodos anidados complejas
`create_supertag`	Define nuevas superetiquetas en tu esquema
`create_field`	Define nuevos campos en tu esquema
`add_field_value`	Agrega valores de campo a nodos existentes
`set_node_name`	Renombra nodos existentes (solo nodos de texto plano)

Prompts (4 plantillas)

create-task - Creación estructurada de tareas con fechas de vencimiento y prioridades
create-project - Estructuras de proyectos con objetivos e hitos
create-meeting-notes - Documentación de reuniones con asistentes y elementos de acción
create-knowledge-entry - Entradas de base de conocimiento con categorías y fuentes

Recursos (4 disponibles)

api-docs - Referencia completa de la API de entrada de Tana
node-types - Ejemplos detallados de todos los tipos de nodos admitidos
examples - Patrones de uso comunes y mejores prácticas
server-info - Estado actual del servidor y configuración

Requisitos previos

Un espacio de trabajo de Tana con acceso a la API habilitado
Token de API de Tana (consulta Cómo obtener tu token de API de Tana)
Uno de los siguientes clientes MCP:
- Raycast con funciones de IA
- Claude Code CLI
- Claude Desktop
- Cualquier otro cliente compatible con MCP

Cómo obtener tu token de API de Tana

Abre Tana en tu navegador
Haz clic en el ícono de Configuración (engranaje) en la esquina inferior izquierda
Navega a API tokens
Haz clic en Crear nuevo token
Dale un nombre descriptivo (por ejemplo, "Servidor MCP")
Copia el token inmediatamente: no se mostrará nuevamente

Instalación

Raycast

Raycast integra servidores MCP directamente en sus funciones de IA. Una vez configurado, usa @tana-mcp en cualquier interacción de IA de Raycast.

Paso 1: Instala la extensión MCP

Abre Raycast
Busca "Store" y abre la tienda de Raycast
Busca "Model Context Protocol"
Instala la extensión MCP

Paso 2: Agrega el servidor MCP de Tana

Abre Raycast y busca "Install Server" (desde la extensión MCP)
Completa el formulario:

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

Agrega las variables de entorno:
- TANA_API_TOKEN: Tu token de API de Tana
- TANA_DEFAULT_TARGET: INBOX (opcional - consulta Opciones de configuración)

Alternativa: Copia este JSON antes de abrir "Install Server": Raycast completará el formulario automáticamente:

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

Paso 3: Úsalo en Raycast AI

Una vez instalado, menciona el servidor en cualquier interacción de IA de Raycast:

Quick AI: Escribe tu consulta y menciona @Tana
AI Chat: Inicia un chat y usa @Tana para invocar herramientas
AI Commands: Crea comandos personalizados que usen las herramientas de Tana

Ejemplo: "@Tana Crea una tarea llamada 'Revisar informe trimestral' con prioridad alta"

Para más detalles, consulta la documentación de MCP de Raycast.

Claude Code (CLI)

Agrega Tana MCP como un servidor a nivel de usuario disponible en todas tus sesiones de 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

O para un alcance de proyecto (solo el directorio actual):

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

Verifica que esté instalado:

claude mcp list

Claude Desktop

Agrega al archivo de configuración de 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"
      }
    }
  }
}

Reinicia Claude Desktop después de guardar.

Otros clientes MCP

Para cualquier cliente compatible con MCP, configura con:

Configuración	Valor
Comando	`npx`
Argumentos	`-y tana-mcp`
Entorno	`TANA_API_TOKEN=your-token`

O si está instalado globalmente (npm install -g tana-mcp):

Configuración	Valor
Comando	`tana-mcp`
Entorno	`TANA_API_TOKEN=your-token`

Opciones de configuración

Variable	Requerida	Predeterminado	Descripción
`TANA_API_TOKEN`	Sí	-	Tu token de API de Tana
`TANA_DEFAULT_TARGET`	No	Raíz de la biblioteca	Dónde colocar los nodos cuando no se especifica un destino. Usa `INBOX` para la bandeja de entrada, o cualquier ID de nodo
`TANA_API_ENDPOINT`	No	El predeterminado de Tana	Endpoint de API personalizado (solo uso avanzado)

Opciones de destino

Omite TANA_DEFAULT_TARGET: Los nodos aparecen en la raíz de la biblioteca
INBOX: Los nodos van a tu bandeja de entrada de Tana para procesamiento posterior
Cualquier ID de nodo: Los nodos se crean bajo ese nodo específico

Uso

Herramientas disponibles

Creación básica de nodos

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

Tareas con casillas de verificación

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

Contenido con formato enriquecido

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

Estructuras anidadas

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

Operaciones de esquema

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

Ejemplos de prompts

Aquí hay prompts en lenguaje natural que funcionan bien:

Lo que quieres	Ejemplo de prompt
Captura rápida	"Agrega 'Llamar al dentista' a mi bandeja de entrada de Tana"
Tarea con detalles	"Crea una tarea de alta prioridad 'Terminar informe' para el viernes"
Notas de reunión	"Crea notas de reunión para mi 1:1 con Sarah, hablamos sobre los objetivos del Q1"
Configuración de proyecto	"Configura un nuevo proyecto llamado 'Lanzamiento de la app' con fases de planificación, desarrollo y lanzamiento"
Entrada de conocimiento	"Agrega una nota sobre genéricos de TypeScript con ejemplos"
Enlazar una URL	"Guarda este artículo: https://example.com/interesting-post"

Formato de texto

La herramienta create_formatted_node admite formato de texto enriquecido en los nombres de los nodos:

Formato	Sintaxis	Resultado
Negrita	`text`	texto
Cursiva	`__text__`	texto
Tachado	`~~text~~`	~~texto~~
Resaltado	`^^text^^`	resaltado

También puedes incluir:

Referencias de nodos en línea: Enlaza a otros nodos por ID
Fechas en línea: Enlaces de fecha clicables

Ejemplo:

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

Limitaciones de la API

Estas son limitaciones de la API de entrada de Tana, no del servidor:

Límite	Valor
Nodos por solicitud	100 máximo
Límite de velocidad	1 solicitud/segundo por token
Tamaño de carga útil	5,000 caracteres
Nodos del espacio de trabajo	750,000 máximo

No admitido por la API de Tana:

Leer/consultar nodos existentes (API de solo escritura)
Apuntar a "Hoy" o nodos de fecha relativa
Actualizar nodos de casilla de verificación/booleano
Enlaces que no sean HTTP/HTTPS

Desarrollo

Compilar desde el código fuente

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

Ejecutar localmente

TANA_API_TOKEN=your-token bun run dev

Probar con Claude Code

Apunta Claude Code a tu compilación local:

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

Solución de problemas

"Falta el parámetro esperado: items"

Este error ocurría en versiones anteriores a la 2.0.0. Actualiza a la última versión:

npm install -g tana-mcp@latest

El servidor no se conecta

Verifica tu token: Asegúrate de que TANA_API_TOKEN esté configurado correctamente
Revisa el comando: Asegúrate de que npx esté disponible en tu PATH
Reinicia el cliente: Algunos clientes requieren reinicio después de cambios de configuración
Revisa los registros: Busca mensajes de error en los registros de tu cliente MCP

Los nodos aparecen en la ubicación incorrecta

Configura TANA_DEFAULT_TARGET=INBOX para usar tu bandeja de entrada
O especifica targetNodeId en llamadas de herramientas individuales

set_node_name devuelve error 400

Esto ocurre al intentar renombrar nodos de casilla de verificación/booleano. La API de Tana solo admite renombrar nodos de texto plano.

Errores de límite de velocidad

La API de Tana limita las solicitudes a 1 por segundo. Si estás alcanzando los límites de velocidad, reduce la velocidad de tus solicitudes o agrupa las operaciones.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

Soporte

Problemas: GitHub Issues
Documentación de la API de Tana: tana.inc/docs/input-api
Protocolo MCP: modelcontextprotocol.io

Fuentes:

Tana

Documentación