Skip to content
Tana Logo

Local API/MCP

The Tana Local API provides direct access to your Tana data from the desktop app. It exposes an MCP (Model Context Protocol) endpoint that AI tools can connect to.

Requirements

  • Tana desktop app (latest version)
  • An MCP-compatible client (Claude Code, Gemini CLI, Codex CLI, Cursor, VS Code, etc)

Enable the Local API/MCP

  1. Open Tana desktop
  2. Click your user settings (top right)
  3. Under Tana Labs, enable Local API/MCP server (Alpha)

Connect a client

Claude Code

Go to Options in the OS menu for the Tana desktop app, click Local API settings, and enable the Claude Code option.

This auto-configures the MCP while Tana is running and removes it when
Tana closes.

This will automatically set up the ‘tana-local’ MCP in ~/.claude/.config.json

Option 2: Manual

Add the server

claude mcp add --transport http tana http://127.0.0.1:8262/mcp

Add -s project or -s user to change scope from the default local.

Or add manually to config:

  • Project: .mcp.json in project root
  • User: ~/.claude/settings.json

Authenticate

Run /mcp in Claude Code, select the tana server, and complete the OAuth flow.

A modal opens in the Tana desktop app for approval, then a browser window confirms authentication status.

Codex CLI

Add the server (user scope only)

codex mcp add tana --url http://127.0.0.1:8262/mcp

This writes to ~/.codex/config.toml. This instantly initiates the authentication.

A modal opens in the Tana desktop app for approval, then a browser window confirms authentication status.

Alternatively: Project‑scoped server

Create or edit .codex/config.toml in your project:

Authenticate

Run this in your terminal to initiate the authentication if not already authenticated.

codex mcp login tana

Gemini CLI

Add to .gemini/settings.json (project) or ~/.gemini/settings.json (user):

Restart Gemini CLI. On first use, a browser window opens for OAuth - approve in the Tana desktop modal.

Note: Native HTTP transport (--transport http) has OAuth compatibility issues with the Tana server. Using mcp-remote as a bridge is the reliable method.

Claude Desktop

Claude Desktop doesn't support HTTP transport directly and requires mcp-remote as a bridge.

Navigate to Settings → Developer, and Edit Config. Open to edit the claude_desktop_config.json file and add this to the MCP server config:

Config file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after saving. You should see the “tana” Local MCP server as running when set up correctly.

Available tools

Read

  • list_workspaces — List available workspaces
  • search_nodes — Search using structured queries
  • read_node — Read node content as markdown
  • get_children — Get paginated children of a node
  • list_tags — List tags in a workspace
  • get_tag_schema — Get field definitions for a tag

Mutation

  • import_tana_paste — Import hierarchical content
  • tag — Add/remove tags from nodes
  • set_field_option — Set dropdown field values
  • set_field_content — Set text/number/date field values
  • create_tag — Create new tags
  • add_field_to_tag — Add fields to tags
  • set_tag_checkbox — Configure checkbox behavior
  • check_node / uncheck_node — Mark nodes done/not done
  • trash_node — Move node to trash
  • get_or_create_calendar_node — Get/create calendar nodes
  • edit_node — Edit a node's name and/or description using search-and-replace

Troubleshooting

No “Local API settings” in options - Check that you have enabled the “Local API” feature flag in Tana Labs.

Connection refused - Tana desktop not running or Local API not enabled in Tana Labs.

Authentication fails - Remove and re-add the MCP server, then try authenticating again.

Tools not appearing - Restart your client after adding the configuration.