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

$3

No installation required - run directly:

``bash
npx clear-tangle-mcp
`

$3

`bash
npm install -g clear-tangle-mcp
`

$3

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

Configuration

$3

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

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

$3

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

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

$3

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

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

$3

For automated setups, add credentials to your MCP config:

`json
{
"mcpServers": {
"clear-tangle": {
"command": "npx",
"args": ["-y", "clear-tangle-mcp"],
"env": {
"CLEARTANGLE_API_KEY": "ctak_your_api_key_here",
"CLEARTANGLE_USERNAME": "your@email.com",
"CLEARTANGLE_PASSWORD": "your-password"
}
}
}
}
`

Components

$3

#### 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. set_api_key
- Manually set an API key (recommended)
- Inputs:
- api_key (required): The API key

5. check_auth
- Check current authentication status
- No input required

6. test_connection
- Test backend connectivity and diagnose issues
- No input required

7. logout
- Clear authentication and saved credentials
- No input required

#### Task Tools

8. 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

9. 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

$3

`
Authenticate me with Clear Tangle
`

$3

`
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
`

$3

`
Capture a thought: "Remember to update the documentation"

List my recent thoughts

Delete thought xyz-456
`

$3

`
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

$3

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

$3

`bash


Start the server

npm start

Start in development mode (with file watching)

npm run dev
`

$3

`bash


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
`

$3

`bash
npm run lint
`

$3

`
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

- Auth Storage: API keys or tokens are stored locally at ~/.clear-tangle-mcp/token.json
- Automatic Expiry: Bearer tokens expire after 24 hours; API keys remain valid until revoked
- Secure Credentials: Use environment variables for auto-login, never commit credentials

Troubleshooting

$3

Run the authentication tool:
`
Authenticate me with Clear Tangle
`

$3

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

$3

Bearer tokens expire after 24 hours. Re-authenticate when prompted.

$3

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.