Tana MCP Codemode

🚀 Tana MCP Server

A codemode MCP server for Tana knowledge management. AI writes TypeScript code that executes against the Tana Local API.

🚀 Quick Start

The Tana MCP Server enables AI to write and execute TypeScript code against the Tana Local API. First, ensure you meet the requirements and then follow the installation steps below.

✨ Features

• Codemode Pattern — AI writes executable TypeScript, not structured API calls.
• Tana Local API — Covers workspaces, nodes, tags, fields, calendar, and import.
• Top-level Await — await tana.workspaces.list() works directly.
• Timeout Protection — A maximum execution time of 10s prevents infinite loops.
• Script History — Uses SQLite for persistence, facilitating debugging and replay.
• Retry Logic — Employs exponential backoff for transient failures.
• Debug UI — A WebSocket-based dashboard for testing scripts.

📦 Installation

Option 1: bun (recommended)

# Requires Bun runtime
bun add -g tana-mcp-codemode

Option 2: From source

git clone https://github.com/fabiogaliano/tana-mcp-codemode
cd tana-mcp-codemode
bun install

📚 Documentation

Configuration

MCP Integration

Add the following to your MCP client's configuration:

{
  "mcpServers": {
    "tana": {
      "command": "tana-mcp-codemode",
      "env": {
        "TANA_API_TOKEN": "your_token_here",
        // Optional
        "MAIN_TANA_WORKSPACE": "My Workspace",
        "TANA_SEARCH_WORKSPACES": "My Workspace",
        // Optional: customize where the SQLite history database is stored
        "TANA_HISTORY_PATH": "/path/to/history.db"
      }
    }
  }
}

If installed from source, use bun as the command:

{
  "mcpServers": {
    "tana": {
      "command": "bun",
      "args": ["run", "/path/to/tana-mcp-codemode/src/index.ts"],
      "env": {
        "TANA_API_TOKEN": "your_token_here",
        // Optional
        "MAIN_TANA_WORKSPACE": "My Workspace",
        "TANA_SEARCH_WORKSPACES": "My Workspace",
        // Optional: customize where the SQLite history database is stored
        "TANA_HISTORY_PATH": "/path/to/history.db"
      }
    }
  }
}

💻 Usage Examples

Basic Usage

Search for nodes

const results = await tana.nodes.search({
  textContains: "meeting notes"
});
console.log("Found:", results.length, "nodes");

Complex query

const tasks = await tana.nodes.search({
  and: [
    { hasType: "taskTagId" },
    { is: "todo" },
    { created: { last: 7 } }
  ]
});
console.log({ tasks });

Import content

await tana.import(parentNodeId, `
- Project Alpha #[[^projectTagId]]
  - [[^statusFieldId]]:: Active
  - [[^dueDateFieldId]]:: [[date:2024-03-15]]
`);

Advanced Usage

Debug UI

A WebSocket-based dashboard for testing scripts:

# Start debug server
bun run src/debug-server.ts

# Open http://localhost:3333

Routes:

• http://localhost:3333/#debug — Script execution console
• http://localhost:3333/#benchmark — Codemode vs tana-local performance comparison

Features:

• Real-time script execution
• Workflow event timeline
• Error display with suggestions
• Benchmark results visualization (cost, speed, token usage)

workflow Helper (Debug UI only)

Track multi-step operations with a timeline view:

workflow.start("Processing nodes");
workflow.step("Fetching workspaces");
workflow.progress(5, 100, "Processing");
workflow.complete("Done!");
// Or: workflow.abort("Error message");

⚠️ Important Note

workflow is only available in the Debug UI. It's not exposed in the production MCP prompt.

Building the React UI (optional)

cd ui
bun install
bun run build
cd ..
bun run src/debug-server.ts

🔧 Technical Details

Architecture

src/
├── index.ts              # MCP server entry
├── prompts.ts            # Tool description
├── types.ts              # TypeScript interfaces
├── debug-server.ts       # WebSocket debug UI
├── api/
│   ├── client.ts         # HTTP client (auth, retry, timeouts)
│   ├── tana.ts           # API wrapper → `tana` object
│   └── types.ts          # API type definitions
├── sandbox/
│   ├── executor.ts       # Code execution engine
│   └── workflow.ts       # Progress tracking
├── storage/
│   └── history.ts        # SQLite script history
└── generated/
    └── api.d.ts          # Generated OpenAPI types

ui/                       # React debug dashboard

How It Works

1. AI sends TypeScript code to the execute tool.
2. executor.ts creates an AsyncFunction for top-level await.
3. Code runs with injected tana and console objects.
4. A 10s timeout via Promise.race prevents hangs.
5. console.log() output is captured and returned.
6. Script run is saved to SQLite history.

Script History

Runs are persisted to SQLite:

Old runs (>30 days) are automatically cleaned up on startup.

What Gets Saved

Each script run records:

Development

# Dev mode with watch
bun run dev

# Type check
bun run typecheck

# Regenerate API types from OpenAPI spec
bun run generate

# Run debug server
bun run debug

📄 API Reference

The server exposes a single execute tool. AI writes TypeScript code with access to the tana object:

Workspaces

const workspaces = await tana.workspaces.list();
// → Workspace[] (id, name, homeNodeId)

Nodes

await tana.nodes.search(query, options?)     // → SearchResult[]
await tana.nodes.read(nodeId, maxDepth?)     // → string (markdown)
await tana.nodes.getChildren(nodeId, opts?)  // → { children, total, hasMore }
await tana.nodes.edit({ nodeId, name?, description? })
await tana.nodes.trash(nodeId)
await tana.nodes.check(nodeId)               // mark done
await tana.nodes.uncheck(nodeId)             // mark undone

Tags (Supertags)

await tana.tags.listAll(workspaceId)              // All workspace supertags (paginated)
await tana.tags.getSchema(tagId, opts?)            // opts: { includeInheritedFields? }
await tana.tags.modify(nodeId, action, tagIds)     // action: "add" | "remove"
await tana.tags.create({ workspaceId, name, description?, extendsTagIds?, showCheckbox? })
await tana.tags.addField({ tagId, name, dataType, ... })
await tana.tags.setCheckbox({ tagId, showCheckbox, doneStateMapping? })

Fields

await tana.fields.setOption(nodeId, attributeId, optionId)   // dropdown fields
await tana.fields.setContent(nodeId, attributeId, content)   // text/date/url fields

Calendar

await tana.calendar.getOrCreate(workspaceId, granularity, date?)
// granularity: "day" | "week" | "month" | "year"

Import (Tana Paste)

await tana.import(parentNodeId, tanaPasteContent)
// → { success, nodeIds?, error? }

Utility

tana.workspace                // Pre-resolved default workspace (from MAIN_TANA_WORKSPACE) or null
tana.format(data)             // Compact display of any API response
await tana.health()           // → { status: "ok" }

📄 License

MIT