lydgate/intend-mcp

Intend.do MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to your Intend.do account, allowing them to help you manage your intentions, track outcomes, and control your timer.

What is an MCP Server?

An MCP server is an intermediary that allows AI assistants (like Claude in Cursor) to interact with external services through a standardized protocol. This server exposes:

• Tools: Actions like adding intentions, completing tasks, starting timers
• Resources: Data like today's intentions, goals, timer status
• Prompts: (Coming soon) Pre-defined templates for common queries

Why Build This?

Since you use Intend.do frequently, having an MCP server means you can:

• Ask your AI assistant: "Add 'Review project proposal' to my intentions"
• Get updates: "What's my next action?"
• Track work: "Mark my current task as complete"
• Control timers: "Start a 25-minute pomodoro"

All without leaving your AI chat interface!

Setup

1. Install Dependencies

npm install

2. Get Your Auth Token

You need either:

• Personal auth token (for testing/personal use): Log in to intend.do/apiclient/docs and copy your token
• OAuth2 access token (for applications): Follow the OAuth2 instructions to create an OAuth2 app

3. Configure Authentication

Create a .env file in the project root:

cp .env.example .env

Then edit .env and add your token:

# For personal auth token:
INTEND_AUTH_TOKEN=your_auth_token_here

# OR for OAuth2:
INTEND_ACCESS_TOKEN=your_access_token_here

Note: The .env file is already in .gitignore, so your token won't be committed. Environment variables (set via export) will also work if you prefer that method.

4. Build and Run

npm run build
npm start

Or for development:

npm run dev

Configuration for Cursor/Claude Desktop

Add this to your MCP settings (usually in ~/.config/cursor/mcp.json or similar):

Option 1: Using .env file (recommended - keeps tokens out of config)

If you've set up .env in the project directory, the server will automatically load it:

{
  "mcpServers": {
    "intend": {
      "command": "node",
      "args": ["/path/to/intend-mcp/dist/index.js"],
      "cwd": "/path/to/intend-mcp"
    }
  }
}

Option 2: Environment variables in config

You can also set the token directly in the MCP config:

{
  "mcpServers": {
    "intend": {
      "command": "node",
      "args": ["/path/to/intend-mcp/dist/index.js"],
      "env": {
        "INTEND_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

Or for OAuth2 access token:

{
  "mcpServers": {
    "intend": {
      "command": "node",
      "args": ["/path/to/intend-mcp/dist/index.js"],
      "env": {
        "INTEND_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Available Tools

• get_next_action - Get what you should do next
• get_today_data - Get full today page data
• get_goals - List active goals (tasks are assigned to goals, numbers identify goal assignments)
• add_intention - Add new intention(s)
• complete_intention - Mark an intention complete
• post_outcome - Post what you actually did
• mark_not_today - Mark intention as "not today"
• move_to_current - Move intention to top of list
• get_timer_status - Get current timer state
• start_pomodoro - Start pomodoro timer
• start_break - Start break timer

Available Resources

• intend://today/core - Core today data
• intend://today/full - Full today page
• intend://goals - Active goals (numbers identify which goals tasks are assigned to)
• intend://userinfo - User information

Example Usage

Once configured, you can ask your AI assistant things like:

• "What's my next action in Intend?"
• "Add 'Write blog post' to my intentions"
• "Mark the current task as complete"
• "What are my active goals?"
• "Start a 25-minute pomodoro"

Development

# Watch mode for development
npm run watch

# Run in development mode
npm run dev

API Reference

This server wraps the Intend.do API. See that documentation for details on the underlying endpoints.

Security Note

Keep your auth tokens secure! Never commit them to version control. Consider using a secrets manager or environment variable management tool.

License

MIT