MCP Server

Connect to AI assistants via Model Context Protocol

The Clear Tangle MCP Server enables AI assistants like Claude, Cursor, and Kiro to interact directly with your Clear Tangle account. Manage tasks, capture thoughts, and get AI planning—all through natural conversation with your favorite AI assistant.

What is MCP?

The Model Context Protocol (MCP) is a standard that allows AI assistants to use external tools and data sources. Our MCP server provides 21 tools for task management, thought capture, and AI planning.

Supported Platforms

Claude Desktop

Official support

Cursor

IDE integration

Kiro

AI development

Installation

No installation required—use npx to run directly:

Run with npxbash
npx clear-tangle-mcp

Or install globally:

Global installationbash
npm install -g clear-tangle-mcp

Configuration

Claude Desktop

Config file locations:

  • • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • • Linux: ~/.config/claude/claude_desktop_config.json
claude_desktop_config.jsonjson
{
  "mcpServers": {
    "clear-tangle": {
      "command": "npx",
      "args": ["-y", "clear-tangle-mcp"],
      "env": {
        "BACKEND_URL": "https://app.cleartangle.com/api",
        "LOGIN_URL": "https://app.cleartangle.com/login"
      }
    }
  }
}

Cursor

Config: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/settings.json

Same JSON format as Claude Desktop.

Kiro

Config: ~/.kiro/mcp-servers.json

mcp-servers.jsonjson
{
  "servers": {
    "clear-tangle": {
      "command": "npx",
      "args": ["-y", "clear-tangle-mcp"],
      "environment": {
        "BACKEND_URL": "https://app.cleartangle.com/api",
        "LOGIN_URL": "https://app.cleartangle.com/login"
      }
    }
  }
}

Authentication

Four ways to authenticate:

1. API Key (Recommended)

Best for automation

Create an API key in Settings > API Keys and add it to your config:

"env": {
  "CLEARTANGLE_API_KEY": "ctak_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "BACKEND_URL": "https://app.cleartangle.com/api"
}

API keys don't expire and persist across restarts. Learn more about API keys

2. Browser Auth

Say "authenticate with Clear Tangle" to your AI assistant. A browser window opens, you log in, and the token is captured automatically.

3. Credential Auth

Set environment variables for auto-login:

"env": {
  "CLEARTANGLE_USERNAME": "your@email.com",
  "CLEARTANGLE_PASSWORD": "your-password"
}

4. Manual Token/Key

Say "set my Clear Tangle API key to [key]" or "set my Clear Tangle token to [token]" at runtime.

Token Storage

Credentials are stored locally at ~/.clear-tangle-mcp/token.json. JWT tokens expire after 24 hours; API keys persist indefinitely until revoked.

Available Tools (21)

Authentication (7)

authenticate

Browser-based OAuth login

login_with_credentials

Email/password login

set_api_key

Set API key (recommended)

set_token

Manually set JWT token

check_auth

Check auth status

test_connection

Diagnose connectivity

logout

Clear credentials

Tasks (7)

list_tasks

List with filters

get_task

Get task details

create_task

Create new task

update_task

Update task

complete_task

Mark complete

delete_task

Delete task

get_tasks_dashboard

Dashboard view

Thoughts (5)

list_thoughts

List captures

get_thought

Get capture details

capture_thought

Create capture

update_thought

Update capture

delete_thought

Delete capture

Plans (2)

get_plan

Get current plan

generate_plan

Generate new plan

Example Conversations

Authenticate me with Clear Tangle
Create a task called "Review PR #123" with high priority
Show me my tasks for today
Capture this thought: "Remember to update the documentation"
Generate a priority plan for the week
What tasks are overdue?
Mark task xyz-123 as completed

Security Best Practices

  • Use browser-based authentication for interactive use
  • Store credentials in secure environment managers, not config files
  • Rotate passwords regularly
  • Set file permissions: chmod 600 ~/.clear-tangle-mcp/token.json
  • Keep MCP configuration files out of version control

Environment Variables

VariableDefaultDescription
CLEARTANGLE_API_KEY(none)API key (recommended)
BACKEND_URLhttps://app.cleartangle.com/apiAPI base URL
LOGIN_URLhttps://app.cleartangle.com/loginLogin page URL
CLEARTANGLE_USERNAME(none)Auto-login email
CLEARTANGLE_PASSWORD(none)Auto-login password

Related Documentation

API Keys GuideAPI ReferenceSlack Integration