# Limitless MCP Server
Connect AI assistants to your personal memory through Limitless AI's powerful lifelog system. Access your Pendant recordings, meeting notes, and personal insights directly from Claude, Cursor, or any MCP-compatible AI assistant.
<details>
<summary>🚀 Quick Start (2 minutes)</summary>
```bash
# Install globally
npm install -g @utlyze/limitless-mcp-server
# Or use directly with npx (recommended)
npx @utlyze/limitless-mcp-server
```
Add to your AI assistant config:
```json
{
"mcpServers": {
"limitless": {
"command": "npx",
"args": ["-y", "@utlyze/limitless-mcp-server"],
"env": {
"LIMITLESS_API_KEY": "your-api-key"
}
}
}
}
```
</details>
## What is Limitless?
[Limitless](https://limitless.ai) is a personal AI that captures and organizes everything you've seen, said, or heard. Using their Pendant device or desktop app, Limitless creates a searchable memory of your life that you can query and learn from.
## Features
### 🧠 Personal Memory Access
- List and search through all your lifelogs
- Get AI-powered summaries of your days
- Ask questions about your past conversations and meetings
### 📝 Smart Organization
- Star important memories
- Export memories as markdown
- Filter by date, source, or content
### 🤖 AI Integration
- Natural language search through your memories
- AI-generated daily summaries
- Context-aware answers about your past
## Installation
<details>
<summary>📦 Installation Options</summary>
### Global Installation (Recommended)
```bash
npm install -g @utlyze/limitless-mcp-server
```
### Local Project Installation
```bash
npm install @utlyze/limitless-mcp-server
```
### Direct Usage (No Installation)
```bash
npx @utlyze/limitless-mcp-server
```
</details>
## Configuration
<details>
<summary>🔧 Configuration Steps</summary>
### 1. Get Your API Key
1. Sign up at [limitless.ai](https://limitless.ai)
2. Pair your Pendant or install the desktop app
3. Go to [Web App](https://app.limitless.ai) → Developer → Create API Key
⚠️ **Security Note**: Never share your API key or commit it to version control.
### 2. Configure Your AI Assistant
#### Claude Desktop (macOS)
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"limitless": {
"command": "npx",
"args": ["-y", "@utlyze/limitless-mcp-server"],
"env": {
"LIMITLESS_API_KEY": "your-api-key-here"
}
}
}
}
```
#### Cursor
Add to `.cursor/mcp.json` in your project:
```json
{
"mcpServers": {
"limitless": {
"command": "npx",
"args": ["-y", "@utlyze/limitless-mcp-server"],
"env": {
"LIMITLESS_API_KEY": "your-api-key-here"
}
}
}
}
```
### 3. Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `LIMITLESS_API_KEY` | Your Limitless API key | ✅ Yes | - |
| `LIMITLESS_BASE_URL` | API base URL | No | `https://api.limitless.ai/v1` |
| `DEBUG` | Enable debug logging | No | `false` |
</details>
## Available Tools
<details>
<summary>🛠️ Tool Reference</summary>
### limitless_list_lifelogs
List your lifelogs with powerful filtering options.
**Parameters:**
- `timezone` - Timezone for date filtering (e.g., "America/New_York")
- `date` - Filter by specific date (YYYY-MM-DD)
- `startTime` - Start time filter (HH:MM)
- `endTime` - End time filter (HH:MM)
- `limit` - Number of results (max 100)
- `isStarred` - Show only starred lifelogs
- `includeMarkdown` - Include full markdown content
- `direction` - Sort order (asc/desc)
### limitless_get_lifelog
Get detailed information about a specific lifelog.
**Parameters:**
- `lifelogId` - The ID of the lifelog
- `includeMarkdown` - Include markdown content
- `includeHeadings` - Include content structure
### limitless_search_lifelogs
Search through your memories using natural language.
**Parameters:**
- `query` - Your search query
- `dateFrom` - Start date for search
- `dateTo` - End date for search
- `source` - Filter by source (pendant/desktop/web/mobile)
### limitless_get_daily_summary
Get an AI-generated summary of a specific day.
**Parameters:**
- `date` - Date to summarize (YYYY-MM-DD)
- `timezone` - Your timezone
- `includeActionItems` - Include action items
- `includeKeyTopics` - Include main topics
### limitless_ask_ai
Ask questions about your memories and get AI-powered answers.
**Parameters:**
- `query` - Your question
- `dateFrom` - Context start date
- `dateTo` - Context end date
- `includeContext` - Include source references
### limitless_star_lifelog
Mark important memories by starring them.
**Parameters:**
- `lifelogId` - The lifelog to star/unstar
- `isStarred` - true to star, false to unstar
### limitless_export_markdown
Export your memories as formatted markdown.
**Parameters:**
- `date` - Export specific date
- `dateFrom`/`dateTo` - Export date range
- `includeMetadata` - Include timestamps and metadata
- `groupByDate` - Organize by date
</details>
## Usage Examples
<details>
<summary>💡 Natural Language Examples</summary>
### Basic Queries
```
"Show me all my memories from yesterday"
"What did I discuss in meetings today?"
"Find conversations about the product launch"
"Get my daily summary for Monday"
```
### Advanced Searches
```
"Search for discussions about AI in the last week"
"Show me starred memories from December"
"Export all my meeting notes from this month"
"What action items came up in yesterday's standup?"
```
### AI Questions
```
"What did John say about the budget proposal?"
"When did I last talk about vacation plans?"
"Summarize my conversations about the new feature"
"What decisions were made in the leadership meeting?"
```
### Organization
```
"Star the memory about the product roadmap"
"Export this week's meetings as markdown"
"Show me all my Pendant recordings from home"
```
</details>
## Architecture
<details>
<summary>🏗️ Technical Details</summary>
### Technology Stack
- **Language**: TypeScript
- **MCP SDK**: @modelcontextprotocol/sdk
- **HTTP Client**: Axios
- **Validation**: Zod
- **Node Version**: 16+
### Project Structure
```
src/
├── config/ # Configuration management
├── lib/ # Core libraries
│ ├── limitless-client.ts
│ └── logger.ts
├── tools/ # MCP tool implementations
│ └── lifelogs/ # Lifelog-related tools
└── types/ # TypeScript type definitions
```
### Error Handling
- Comprehensive error messages
- Graceful API failure handling
- Detailed debug logging
- Input validation
### Security
- API key validation at startup
- Secure credential handling
- No credential logging
- HTTPS-only communication
</details>
## Development
<details>
<summary>👩💻 Development Guide</summary>
### Setup
```bash
# Clone the repository
git clone https://github.com/Utlyze/limitless-mcp-server.git
cd limitless-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
```
### Scripts
- `npm run dev` - Development mode with hot reload
- `npm run build` - Build for production
- `npm test` - Run test suite
- `npm run lint` - Check code style
- `npm run typecheck` - Verify TypeScript types
### Testing
```bash
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test suite
npm run test:unit
npm run test:integration
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
</details>
## API Limitations
<details>
<summary>⚠️ Current Limitations</summary>
- **Pendant Only**: Currently limited to Pendant recordings (desktop/web coming soon)
- **Read Only**: No ability to create or modify lifelogs
- **Beta API**: Some features may change as the API evolves
- **Rate Limits**: Standard API rate limits apply
</details>
## Troubleshooting
<details>
<summary>🔍 Common Issues</summary>
### "API Key Required" Error
- Ensure `LIMITLESS_API_KEY` is set in your config
- Check that the key is valid and active
- Verify you've created a key at app.limitless.ai
### "No Lifelogs Found"
- Ensure you have recordings in your account
- Check the date range you're querying
- Verify your Pendant is syncing properly
### Connection Issues
- Check your internet connection
- Verify the API is accessible
- Try the debug mode: `DEBUG=true`
### Tool Not Found
- Restart your AI assistant
- Check the tool name is correct
- Verify MCP server is running
</details>
## Support
- **Documentation**: [limitless.ai/developers](https://limitless.ai/developers)
- **Slack Community**: Join #developers channel
- **GitHub Issues**: [Report bugs here](https://github.com/Utlyze/limitless-mcp-server/issues)
- **Email**: support@limitless.ai
## License
MIT License - see [LICENSE](LICENSE) file for details.
---
Built with ❤️ for the Limitless community. Remember everything, forget nothing.
