Tana MCP Server

Tana MCP Server

A Model Context Protocol (MCP) server that connects to Tana's Input API, enabling AI assistants to create and manipulate data in your Tana workspace.

Table of Contents

• Features
• Prerequisites
• Getting Your Tana API Token
• Installation
  • Raycast
  • Claude Code (CLI)
  • Claude Desktop
  • Other MCP Clients
• Configuration Options
• Usage
  • Available Tools
  • Example Prompts
  • Text Formatting
• API Limitations
• Development
• Troubleshooting
• License

Features

Tools (12 available)

Prompts (4 templates)

• create-task - Structured task creation with due dates and priorities
• create-project - Project structures with goals and milestones
• create-meeting-notes - Meeting documentation with attendees and action items
• create-knowledge-entry - Knowledge base entries with categories and sources

Resources (4 available)

• api-docs - Complete Tana Input API reference
• node-types - Detailed examples of all supported node types
• examples - Common usage patterns and best practices
• server-info - Current server status and configuration

Prerequisites

• A Tana workspace with API access enabled
• Tana API token (see Getting Your Tana API Token)
• One of the following MCP clients:
  • Raycast with AI features
  • Claude Code CLI
  • Claude Desktop
  • Any other MCP-compatible client

Getting Your Tana API Token

1. Open Tana in your browser
2. Click on the Settings icon (gear) in the bottom left
3. Navigate to API tokens
4. Click Create new token
5. Give it a descriptive name (e.g., "MCP Server")
6. Copy the token immediately - it won't be shown again

Installation

Raycast

Raycast integrates MCP servers directly into its AI features. Once configured, use @tana-mcp in any Raycast AI interaction.

Step 1: Install the MCP Extension

1. Open Raycast
2. Search for "Store" and open the Raycast Store
3. Search for "Model Context Protocol"
4. Install the MCP extension

Step 2: Add the Tana MCP Server

1. Open Raycast and search for "Install Server" (from the MCP extension)
2. Fill in the form:

3. Add environment variables:
   • TANA_API_TOKEN: Your Tana API token
   • TANA_DEFAULT_TARGET: INBOX (optional - see Configuration Options)

Alternative: Copy this JSON before opening "Install Server" - Raycast will auto-populate the form:

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

Step 3: Use in Raycast AI

Once installed, mention the server in any Raycast AI interaction:

• Quick AI: Type your query and mention @Tana
• AI Chat: Start a chat and use @Tana to invoke tools
• AI Commands: Create custom commands that use Tana tools

Example: "@Tana Create a task called 'Review quarterly report' with high priority"

For more details, see the Raycast MCP documentation.

---

Claude Code (CLI)

Add Tana MCP as a user-scoped server available in all your Claude Code sessions.

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

Or for project-scoped (current directory only):

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

Verify it's installed:

claude mcp list

---

Claude Desktop

Add to your Claude Desktop configuration file:

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"
      }
    }
  }
}

Restart Claude Desktop after saving.

---

Other MCP Clients

For any MCP-compatible client, configure with:

Or if installed globally (npm install -g tana-mcp):

Configuration Options

Target Options

• Omit TANA_DEFAULT_TARGET: Nodes appear in Library root
• INBOX: Nodes go to your Tana Inbox for later processing
• Any node ID: Nodes created under that specific node

Usage

Available Tools

Basic Node Creation

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

Tasks with Checkboxes

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

Rich Formatted Content

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

Nested Structures

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

Schema Operations

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

Example Prompts

Here are natural language prompts that work well:

Text Formatting

The create_formatted_node tool supports rich text formatting in node names:

You can also include:

• Inline node references: Link to other nodes by ID
• Inline dates: Clickable date links

Example:

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

API Limitations

These are Tana Input API limitations, not server limitations:

Not supported by Tana's API:

• Reading/querying existing nodes (write-only API)
• Targeting "Today" or relative date nodes
• Updating checkbox/boolean nodes
• Non-HTTP/HTTPS links

Development

Building from Source

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

Running Locally

TANA_API_TOKEN=your-token bun run dev

Testing with Claude Code

Point Claude Code to your local build:

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

Troubleshooting

"Missing expected parameter key: items"

This error occurred in versions before 2.0.0. Update to the latest version:

npm install -g tana-mcp@latest

Server not connecting

1. Verify your token: Make sure TANA_API_TOKEN is set correctly
2. Check the command: Ensure npx is available in your PATH
3. Restart the client: Some clients require restart after config changes
4. Check logs: Look for error messages in your MCP client's logs

Nodes appearing in wrong location

• Set TANA_DEFAULT_TARGET=INBOX to use your inbox
• Or specify targetNodeId in individual tool calls

set_node_name returning 400 error

This happens when trying to rename checkbox/boolean nodes. The Tana API only supports renaming plain text nodes.

Rate limiting errors

The Tana API limits requests to 1 per second. If you're hitting rate limits, slow down your requests or batch operations together.

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Tana API Docs: tana.inc/docs/input-api
• MCP Protocol: modelcontextprotocol.io

---

Sources:

• Raycast MCP Documentation
• Raycast MCP Extension
• Tana Input API