What can you do with this server?

The Tana MCP Server enables AI assistants to create and manipulate data in your Tana workspace through write-access to Tana's Input API. **Capabilities:** * **Create various node types:** Plain text, formatted nodes with rich text (bold, italic, strikethrough, highlight, inline references), reference nodes to existing items, date nodes (ISO 8601 formats), URL/link nodes, checkbox/task nodes, and file attachment nodes (base64 encoded) * **Build complex structures:** Create nested node hierarchies with parent-child relationships to organize projects, lists, and other data * **Manage schema:** Define new supertags and fields to extend your workspace's data model, and add field values to existing nodes * **Modify existing data:** Rename existing plain text nodes and apply supertags with optional field values * **Use structured prompts:** Leverage pre-built templates for creating tasks, projects, meeting notes, and knowledge base entries * **Access resources:** View API documentation, node type examples, usage patterns, best practices, and server status information * **Configure node placement:** Control where new nodes are placed (Inbox, Library root, or specific node ID) via environment variables * **Batch operations:** Create up to 100 nodes per request * **Integrate with MCP clients:** Compatible with Raycast, Claude Code (CLI and Desktop), and other MCP-compatible clients **Limitations:** * Write-only operations (cannot read or query existing nodes) * Cannot update checkbox/boolean states after creation * Rate limited to 1 request per second * Maximum 100 nodes per request and 5,000 characters per payload

Which integrations are available for this server?

Provides a runtime environment for the Tana MCP server, which connects to Tana's Input API to create and manipulate nodes, fields, and schemas in Tana workspaces. Enables adding the Tana MCP server to [Raycast](/mcp/servers/integrations/raycast), allowing users to create and manipulate data in Tana workspaces through Raycast's MCP extension.

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

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 : 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:

Install Server

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

How are these scores calculated?

Resources

Need Help?

Report Issue

Reddit Discussion

Related Servers

Tools

View all tools