Local API / MCP

The Tana Outliner Local API provides direct access to Tana Outliner data from the desktop application. It exposes an MCP (Model Context Protocol) endpoint allowing AI tools to connect.

Requirements

• Tana Outliner desktop app (latest version)
• MCP-compatible client (Claude Code, Gemini CLI, Codex CLI, Cursor, VS Code, etc.)
• Desktop app must be running for client connections

Enabling the API

1. Open Tana Outliner desktop
2. Click user settings (top right)
3. Enable "Local API/MCP server (Alpha)" under Tana Labs

Connection details

Setup by client

All CLI tools use the same connection details:

• Transport: HTTP
• URL: http://localhost:8262/mcp

Claude Code

Auto-configure (recommended):

1. In Tana Outliner, go to OS menu → Options → Local API settings
2. Enable the Claude Code option

This auto-configures while Tana Outliner runs and removes the configuration on close.

Manual setup:

claude mcp add --transport http tana-local http://localhost:8262/mcp

Scope options (-s):

• -s local — only you in current project, not shared (default)
• -s project — shared with everyone in project via .mcp.json
• -s user — available to you across all projects

This creates the following configuration:

{
  "mcpServers": {
    "tana-local": {
      "type": "http",
      "url": "http://localhost:8262/mcp"
    }
  }
}

For authentication, run /mcp in Claude Code, select the tana-local server, and complete the OAuth flow. A modal appears in Tana Outliner Desktop for approval, then a browser window confirms authentication status.

Codex CLI

codex mcp add tana-local --url http://localhost:8262/mcp

This creates the following configuration:

[mcp_servers.tana-local]
url = "http://localhost:8262/mcp"

The command writes to user scope (~/.codex/config.toml) by default and initiates authentication immediately. A modal appears in Tana Outliner Desktop for approval, followed by browser confirmation.

For project scope, manually create .codex/config.toml in the project root. Run codex mcp login tana-local to authenticate if not already completed.

Gemini CLI

gemini mcp add -t http -s user tana-local http://localhost:8262/mcp

Scope options (-s):

• -s project — current project only (.gemini/settings.json, default)
• -s user — available across all projects (~/.gemini/settings.json)

This creates the following configuration:

{
  "mcpServers": {
    "tana-local": {
      "url": "http://localhost:8262/mcp",
      "type": "http"
    }
  }
}

To authenticate, start a Gemini CLI session and run /mcp auth. Select the tana-local server, then approve the permissions prompt in Tana Outliner Desktop. A browser window confirms authentication status.

Claude Desktop

Claude Desktop requires the mcp-remote bridge since it cannot connect to local HTTP servers directly.

First, install mcp-remote:

npm install -g mcp-remote

Then in Claude Desktop, go to Settings → Developer and click "Edit Config". This opens claude_desktop_config.json. Add the following to the MCP server config:

Config file locations:

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

{
  "mcpServers": {
    "tana-local": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8262/mcp"]
    }
  }
}

After saving, restart Claude Desktop. The tana-local server should display as running when properly configured.

Personal API token method (advanced fallback)

If your MCP client is not listed here, or if you have OAuth issues with the built-in authorization flow, you can connect to Tana Outliner's local MCP server with a personal API token instead.

This is an advanced fallback. If your client supports the built-in Tana Outliner authorization flow above and it works reliably, that is still the recommended option.

1. In Tana Outliner, open Settings → API tokens
2. Create a Personal Token
3. Create or update your MCP config file for Tana Outliner (you can do this manually or ask your coding agent to do it for you)

Your MCP config should include a Tana Outliner entry like this:

{
  "mcpServers": {
    "tana-local": {
      "transport": {
        "type": "sse",
        "url": "http://127.0.0.1:8262/mcp",
        "headers": {
          "Authorization": "Bearer ${TANA_API_TOKEN}"
        }
      }
    }
  }
}

Set TANA_API_TOKEN in your environment before starting your MCP client.

For example:

• macOS/Linux: run export TANA_API_TOKEN="your-token-here" in the terminal, then start your MCP client from that same shell
• Windows PowerShell: run $env:TANA_API_TOKEN="your-token-here", then start your MCP client

Important notes:

• Tana Outliner Desktop must still be running, because the MCP server is hosted locally
• Keep your personal token private and never commit it to source control
• Prefer using an environment variable rather than pasting the token directly into a config file
• Different MCP clients may use different config file names and schemas, but the required values are the same: the local MCP URL plus the Authorization: Bearer ... header

Verify your connection

After setup, verify the connection is working:

You should see the tana-local server listed with a connected status.

Available tools

Read operations

• list_workspaces - List available workspaces
• search_nodes - Search for nodes using structured queries
• read_node - Read a node and its children as markdown
• get_children - Get paginated children of a node
• list_tags - List supertags in a workspace
• get_tag_schema - Get the schema definition of a supertag

Mutation operations

• import_tana_paste - Import content using Tana Paste format
• tag - Add or remove supertags from a node
• set_field_option - Set a field to a predefined option value
• set_field_content - Set a field's content to a string value
• create_tag - Create a new supertag
• add_field_to_tag - Add a field to an existing supertag
• set_tag_checkbox - Configure the done checkbox for a supertag
• check_node / uncheck_node - Check or uncheck a node's checkbox
• trash_node - Move a node to trash
• get_or_create_calendar_node - Get or create a calendar node
• edit_node - Edit a node's name or description using search-and-replace

Troubleshooting