YearAtAGlance MCP Server

MCP (Model Context Protocol) server for integrating YearAtAGlance calendar with Claude Code and other MCP-compatible AI assistants.

Installation

npm install -g @yearataglance/mcp-server

Or use directly with npx:

npx @yearataglance/mcp-server

Configuration

1. Get your API Key

1. Go to YearAtAGlance
2. Navigate to Profile > API Keys
3. Create a new API key with the permissions you need
4. Copy the key (it's only shown once!)

2. Configure Claude Code

Add to your ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "yearataglance": {
      "command": "npx",
      "args": ["@yearataglance/mcp-server"],
      "env": {
        "YAAG_API_KEY": "your-api-key-here",
        "YAAG_API_URL": "https://yearataglance-backend-production.up.railway.app/api/v1"
      }
    }
  }
}

Available Tools

Events

| Tool | Description | |------|-------------| | yaag_list_events | List all events, optionally filtered by year and category | | yaag_get_event | Get details of a specific event | | yaag_create_event | Create a new event | | yaag_update_event | Update an existing event | | yaag_delete_event | Delete an event | | yaag_get_heatmap | Get event density heatmap for a year |

Categories

| Tool | Description | |------|-------------| | yaag_list_categories | List all categories | | yaag_get_category | Get details of a specific category | | yaag_create_category | Create a new category | | yaag_update_category | Update an existing category | | yaag_delete_category | Delete a category |

AI

| Tool | Description | |------|-------------| | yaag_ai_status | Check AI service status | | yaag_ai_create_milestone | Create event from natural language | | yaag_ai_analyze_year | Get AI analysis of a year's events | | yaag_ai_chat | Chat with AI about your calendar |

Usage Examples

Once configured, you can use natural language in Claude Code:

"Show me all my events for 2025"
"Create an event called 'Team Offsite' from March 10-12"
"What categories do I have?"
"Create a new category called 'Health' with green color"
"Delete the event with ID xyz123"

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | YAAG_API_KEY | Yes | - | Your YearAtAGlance API key | | YAAG_API_URL | No | Production URL | API base URL |

Permissions

API keys can have different permissions:

• read: List and view events/categories
• write: Create, update, delete events/categories
• ai: Use AI features (milestone creation, analysis, chat)

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT