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.

Features
Prerequisites
Getting Your Tana API Token
Installation
Configuration Options
Usage
API Limitations
Development
Troubleshooting
License

Features

Tools (12 available)

Tool	Description
`create_plain_node`	Create simple text nodes with optional supertags
`create_formatted_node`	Create nodes with rich formatting and inline references
`create_reference_node`	Create references to existing nodes
`create_date_node`	Create date nodes (supports various ISO 8601 formats)
`create_url_node`	Create URL/link nodes
`create_checkbox_node`	Create checkbox/task nodes
`create_file_node`	Create file attachment nodes (base64 encoded)
`create_node_structure`	Create complex nested node hierarchies
`create_supertag`	Define new supertags in your schema
`create_field`	Define new fields in your schema
`add_field_value`	Add field values to existing nodes
`set_node_name`	Rename existing nodes (plain nodes only)

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

Open Tana in your browser
Click on the Settings icon (gear) in the bottom left
Navigate to API tokens
Click Create new token
Give it a descriptive name (e.g., "MCP Server")
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

Open Raycast
Search for "Store" and open the Raycast Store
Search for "Model Context Protocol"
Install the MCP extension

Step 2: Add the Tana MCP Server

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

Field	Value
Name	`Tana`
Type	`stdio`
Command	`npx`
Arguments	`-y tana-mcp`

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:

Setting	Value
Command	`npx`
Arguments	`-y tana-mcp`
Environment	`TANA_API_TOKEN=your-token`

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

Setting	Value
Command	`tana-mcp`
Environment	`TANA_API_TOKEN=your-token`

Configuration Options

Variable	Required	Default	Description
`TANA_API_TOKEN`	Yes	-	Your Tana API token
`TANA_DEFAULT_TARGET`	No	Library root	Where to place nodes when no target specified. Use `INBOX` for inbox, or any node ID
`TANA_API_ENDPOINT`	No	Tana's default	Custom API endpoint (advanced use only)

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:

What you want	Example prompt
Quick capture	"Add 'Call dentist' to my Tana inbox"
Task with details	"Create a high-priority task 'Finish report' due Friday"
Meeting notes	"Create meeting notes for my 1:1 with Sarah, we discussed Q1 goals"
Project setup	"Set up a new project called 'App Launch' with planning, development, and release phases"
Knowledge entry	"Add a note about TypeScript generics with examples"
Link a URL	"Save this article: https://example.com/interesting-post"

Text Formatting

The create_formatted_node tool supports rich text formatting in node names:

Format	Syntax	Result
Bold	`text`	text
Italic	`__text__`	text
Strikethrough	`~~text~~`	~~text~~
Highlight	`^^text^^`	highlighted

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:

Limit	Value
Nodes per request	100 maximum
Rate limit	1 request/second per token
Payload size	5,000 characters
Workspace nodes	750,000 maximum

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

Verify your token: Make sure TANA_API_TOKEN is set correctly
Check the command: Ensure npx is available in your PATH
Restart the client: Some clients require restart after config changes
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:

Tana