Clear Tangle MCP Server

A Model Context Protocol (MCP) server for the Clear Tangle API - enabling AI assistants to manage tasks, capture thoughts, and generate AI-powered plans.

Installation

Using npx (Recommended)

No installation required - run directly:

npx clear-tangle-mcp

Install from npm

npm install -g clear-tangle-mcp

Manual Installation

git clone https://github.com/your-org/clear-tangle-mcp.git
cd clear-tangle-mcp
npm install

Configuration

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 Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "clear-tangle": {
      "command": "npx",
      "args": ["-y", "clear-tangle-mcp"]
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings > MCP Servers):

{
  "mcpServers": {
    "clear-tangle": {
      "command": "npx",
      "args": ["-y", "clear-tangle-mcp"]
    }
  }
}

Kiro

Add to ~/.kiro/mcp-servers.json:

{
  "servers": {
    "clear-tangle": {
      "command": "npx",
      "args": ["-y", "clear-tangle-mcp"]
    }
  }
}

With Auto-Login Credentials

For automated setups, add credentials to your MCP config:

{
  "mcpServers": {
    "clear-tangle": {
      "command": "npx",
      "args": ["-y", "clear-tangle-mcp"],
      "env": {
        "CLEARTANGLE_USERNAME": "[email protected]",
        "CLEARTANGLE_PASSWORD": "your-password"
      }
    }
  }
}

Components

Tools (20 total)

Authentication Tools

1. authenticate

   • Start browser-based OAuth login
   • Opens browser, user logs in, token is captured automatically
   • No input required

2. login_with_credentials

   • Login with email and password
   • Inputs:
     • username (optional): Email address (uses env var if not provided)
     • password (optional): Password (uses env var if not provided)

3. set_token

   • Manually set an authentication token
   • Inputs:
     • token (required): The authentication token

4. check_auth

   • Check current authentication status
   • No input required

5. test_connection

   • Test backend connectivity and diagnose issues
   • No input required

6. logout

   • Clear authentication and saved credentials
   • No input required

Task Tools

7. list_tasks

   • List all tasks with optional filters
   • Inputs:
     • status (optional): Filter by status (pending, in_progress, completed, cancelled)
     • priority (optional): Filter by priority (critical, high, medium, low)
     • category (optional): Filter by category name

8. get_task

   • Get details of a specific task
   • Inputs:
     • id (required): Task ID (UUID)

9. create_task

   • Create a new task
   • Inputs:
     • title (required): Task title
     • description (optional): Task description
     • due_date (optional): Due date in YYYY-MM-DD format
     • due_time (optional): Due time in HH:MM format
     • priority (optional): Priority level (default: medium)
     • category (optional): Category name

10. update_task

    • Update an existing task
    • Inputs:
      • id (required): Task ID (UUID)
      • title (optional): New title
      • description (optional): New description
      • due_date (optional): New due date
      • due_time (optional): New due time
      • priority (optional): New priority
      • status (optional): New status
      • category (optional): New category

11. complete_task

    • Mark a task as completed
    • Inputs:
      • id (required): Task ID (UUID)

12. delete_task

    • Delete a task
    • Inputs:
      • id (required): Task ID (UUID)

13. get_tasks_dashboard

    • Get tasks organized by timeframe (today, this week, upcoming, overdue)
    • No input required

Thought Tools

14. list_thoughts

    • List all captured thoughts
    • Inputs:
      • limit (optional): Maximum number of thoughts to return

15. get_thought

    • Get a specific thought by ID
    • Inputs:
      • id (required): Thought ID (UUID)

16. capture_thought

    • Capture a new thought or idea
    • Inputs:
      • content (required): The thought content

17. update_thought

    • Update an existing thought
    • Inputs:
      • id (required): Thought ID (UUID)
      • content (required): New thought content

18. delete_thought

    • Delete a thought
    • Inputs:
      • id (required): Thought ID (UUID)

Plan Tools

19. get_plan

    • Get the current AI-generated priority plan
    • No input required

20. generate_plan

    • Generate a new AI priority plan based on current tasks
    • Inputs:
      • context (optional): Additional context for plan generation (e.g., "Focus on work tasks today")

Usage Examples

Authenticate with Clear Tangle

Authenticate me with Clear Tangle

Manage Tasks

List my tasks

Create a task called "Review PR #123" with high priority

Show me my tasks due this week

Update task abc-123 to set priority to critical

Mark task abc-123 as completed

Delete task abc-123

Capture Thoughts

Capture a thought: "Remember to update the documentation"

List my recent thoughts

Delete thought xyz-456

Generate Plans

Generate a priority plan for today

Generate a plan focused on work tasks

Show me my current plan

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | CLEARTANGLE_USERNAME | Auto-login email | (none) | | CLEARTANGLE_PASSWORD | Auto-login password | (none) |

Development

Setup

git clone https://github.com/your-org/clear-tangle-mcp.git
cd clear-tangle-mcp
npm install

Running Locally

# Start the server
npm start

# Start in development mode (with file watching)
npm run dev

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run authentication tests
npm run test:auth

Linting

npm run lint

Project Structure

clear-tangle-mcp/
├── src/
│   ├── index.js              # Main MCP server implementation
│   └── test/
│       ├── index.test.js     # Comprehensive test suite
│       └── auth_test.js      # Authentication tests
├── docs/
│   ├── MCP_SERVER_CONFIG.md  # Configuration reference
│   └── MCP_INTEGRATION_GUIDE.md  # Integration guide
├── package.json
├── vitest.config.js
└── README.md

Security

• Token Storage: Tokens are stored locally at ~/.clear-tangle-mcp/token.json
• Automatic Expiry: Tokens expire after 24 hours
• Secure Credentials: Use environment variables for auto-login, never commit credentials

Troubleshooting

"Not authenticated" Error

Run the authentication tool:

Authenticate me with Clear Tangle

"Cannot connect to backend" Error

1. Check your network connection
2. Verify BACKEND_URL is correct
3. Run test_connection tool to diagnose

Token Expired

Tokens expire after 24 hours. Re-authenticate when prompted.

MCP Server Not Starting

1. Ensure Node.js >= 18 is installed: node --version
2. Verify the config JSON is valid
3. Check that the path to the server is correct

License

MIT License - see LICENSE for details.