🔮 Limitless MCP


> Connect your Limitless Pendant data to Claude and other LLMs via the Model Context Protocol (MCP).

Limitless MCP is a server implementation of the Model Context Protocol that provides seamless access to your Limitless API data for AI assistants like Claude.

✨ Features

- 🔍 Enhanced Search with relevance-based scoring and content snippets
- 🔮 Semantic Search using text embeddings for concept-based retrieval
- 📅 Natural Language Time parsing for intuitive date filtering (e.g., "last week")
- 📝 Smart Summarization at different detail levels and focus areas
- 📄 Transcript Generation in multiple formats for easy reading
- 📊 Time Analysis to understand your recording patterns
- 🔎 Content Filtering by speaker, type, or timeframe
- 🧠 Topic Extraction to identify key themes across lifelogs
- 😊 Sentiment Analysis for conversations with speaker breakdown
- 🔌 Plugin Architecture for extending functionality with custom features
- ⚡ Performance Optimization with configurable caching
- 🎛️ Customizable via environment variables
- 🔒 Secure Authentication using your Limitless API key
- 🔄 Seamless Integration with Claude Desktop, Cursor, and other MCP-compatible clients

📋 Prerequisites

- Node.js 18 or higher (required for native fetch API and ReadableStream support)
- ⚠️ Important: Node.js 16 and below are NOT supported
- To check your version: node --version
- To upgrade: Visit nodejs.org or use nvm
- A Limitless account with a paired Pendant
- A Limitless API key (available to Pendant owners)

🚀 Installation

``bash
npm install -g limitless-mcp
`

🔧 Configuration & Setup

$3

1. Open 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

2. Add the Limitless MCP server to your configuration:

`json
{
"mcpServers": {
"limitless-mcp": {
"command": "npx",
"args": ["-y", "limitless-mcp"],
"env": {
"LIMITLESS_API_KEY": "your-api-key-here"
}
}
}
}
`

3. Restart Claude Desktop

$3

1. Open your Cursor MCP configuration file:
- macOS: ~/.cursor/mcp.json
- Windows: %USERPROFILE%\.cursor\mcp.json
- Linux: ~/.cursor/mcp.json

2. Add the Limitless MCP server to your configuration:

`json
{
"mcpServers": {
"limitless-mcp": {
"command": "npx",
"args": ["-y", "limitless-mcp"],
"env": {
"LIMITLESS_API_KEY": "your-api-key-here"
}
}
}
}
`

3. Restart Cursor

$3

Any application that supports the Model Context Protocol can use limitless-mcp with a similar configuration. The essential elements are:

`json
{
"command": "npx",
"args": ["-y", "limitless-mcp"],
"env": {
"LIMITLESS_API_KEY": "your-api-key-here"
}
}
`

🎮 Usage

Once configured, you can interact with your Limitless data using natural language within Claude or other MCP-enabled AI assistants.

$3

- List recent lifelogs:
`
Show me my recent lifelogs.
`

- Search for specific content:
`
Search my lifelogs for conversations about artificial intelligence.
`

- Get a daily summary:
`
Give me a summary of my day on May 1, 2025.
`

- Retrieve a full conversation:
`
Show me the full text of lifelog OFe86CdN11YCe22I9Jv4.
`

- Generate a transcript:
`
Create a dialogue transcript from lifelog OFe86CdN11YCe22I9Jv4.
`

- Analyze recording time:
`
Show me a time analysis of my recordings from last week.
`

- Filter by speaker:
`
Filter lifelog OFe86CdN11YCe22I9Jv4 to only show what Jake said.
`

🧰 Available Tools

$3

#### list_lifelogs
Lists your lifelogs with filtering options:
- limit: Maximum number of lifelogs to return (default: 10)
- date: Date in YYYY-MM-DD format
- timezone: IANA timezone specifier (e.g., "America/Los_Angeles")
- start: Start date/time
- end: End date/time
- direction: Sort direction ("asc" or "desc")
- includeContent: Whether to include markdown content
- fields: Specific fields to include (title, time, id, etc.)

#### get_paged_lifelogs
Navigates through paginated results:
- cursor: Pagination cursor from previous results
- limit: Maximum number of lifelogs to return
- date, timezone, direction: Same as above
- includeContent: Whether to include markdown content
- fields: Specific fields to include (title, time, id, etc.)

#### search_lifelogs
Searches your lifelogs with relevance-based scoring:
- query: Text to search for
- limit: Maximum number of results to return
- date, timezone, start, end: Same as above
- searchMode: Search mode ("basic" or "advanced" with scoring)
- includeSnippets: Whether to include matching content snippets

#### get_lifelog
Retrieves a specific lifelog with selective field retrieval:
- id: The ID of the lifelog to retrieve
- includeContent: Whether to include full content or just metadata
- fields: Specific fields to include (title, time, speakers, etc.)

#### get_lifelog_metadata
Retrieves only metadata about a lifelog (faster than full content):
- id: The ID of the lifelog to retrieve metadata for

#### filter_lifelog_contents
Filters lifelog content by various criteria:
- id: The ID of the lifelog to filter
- speakerName: Filter by speaker name
- contentType: Filter by content type (e.g., heading1, blockquote)
- timeStart: Filter content after this time (ISO-8601)
- timeEnd: Filter content before this time (ISO-8601)

#### generate_transcript
Creates a formatted transcript from a lifelog:
- id: The ID of the lifelog to generate transcript from
- format: Transcript format style ("simple", "detailed", or "dialogue")

#### get_time_summary
Provides time-based analytics of your recordings:
- date: Date in YYYY-MM-DD format
- timezone: IANA timezone specifier
- start: Start date for range analysis
- end: End date for range analysis
- groupBy: How to group statistics ("hour", "day", or "week")

#### get_day_summary
Provides a formatted summary of a specific day's lifelogs:
- date: Date in YYYY-MM-DD format
- timezone: IANA timezone specifier

$3

#### summarize_lifelog
Creates intelligent summaries at different levels of detail:
- id: The ID of the lifelog to summarize
- level: Level of summarization detail ("brief", "detailed", or "comprehensive")
- focus: Focus of the summary ("general", "key_points", "decisions", "questions", "action_items")

#### summarize_lifelogs
Summarizes multiple lifelogs with optional combined view:
- ids: Array of lifelog IDs to summarize
- level: Level of detail ("brief" or "detailed")
- combinedView: Whether to provide a combined summary

#### extract_topics
Identifies key topics and themes across lifelogs:
- ids: Array of lifelog IDs to analyze
- maxTopics: Maximum number of topics to extract
- minOccurrences: Minimum occurrences required for a topic
- mode: Extraction mode ("keywords" or "phrases")
- excludeCommonWords: Whether to exclude common English words

#### analyze_sentiment
Analyzes sentiment in lifelog content:
- id: The ID of the lifelog to analyze sentiment for
- bySpeaker: Whether to analyze sentiment by speaker
- includeSentences: Whether to include individual sentences in the analysis

#### compare_sentiment
Compares sentiment across multiple lifelogs:
- ids: Array of lifelog IDs to compare sentiment
- bySpeaker: Whether to compare sentiment by speaker across lifelogs

$3

#### manage_cache
Manages the caching system:
- action: Action to perform ("stats" or "clear")

#### manage_plugins
Manages the plugin system:
- action: Action to perform ("list", "enable", "disable", or "info")
- name: Plugin name for enable/disable/info actions

$3

#### Content Processor Plugin

##### process_content
Processes and transforms lifelog content:
- id: The ID of the lifelog to process
- operations: List of operations to perform (filter, replace, extract, transform)
- format: Output format (markdown, text, or json)

##### batch_process
Processes multiple lifelogs with the same operations:
- ids: Array of lifelog IDs to process
- operations: List of operations to perform
- mergeResults: Whether to merge results into a single output

#### Decorator Plugin

##### apply_template
Applies templates to format lifelog content:
- id: The ID of the lifelog to format
- template: Name of the template to use or custom template string
- variables: Additional variables to use in the template

##### manage_templates
Manages content templates:
- action: Action to perform ("list", "get", "add", or "delete")
- name: Template name for get/add/delete actions
- template: Template content for add action

#### Semantic Search Plugin

##### create_embeddings
Creates embeddings for a lifelog to enable semantic search:
- id: The ID of the lifelog to create embeddings for
- chunkSize: Size of text chunks for embeddings (in characters)
- chunkOverlap: Overlap between chunks (in characters)
- forceRefresh: Whether to force refresh embeddings

##### semantic_search
Searches for semantically similar content:
- query: The query to search for semantically similar content
- ids: Optional array of specific lifelog IDs to search within
- topK: Number of top results to return
- threshold: Similarity threshold (0-1)

##### manage_embeddings
Manages semantic search embeddings:
- action: Action to perform ("list", "delete", "clear", or "info")
- id: Lifelog ID for delete/info actions

#### Time Parser Plugin

##### parse_time_reference
Parses natural language time references:
- timeReference: Natural language time reference (e.g., "yesterday", "last week")
- timezone: IANA timezone specifier
- referenceDate: Reference date (defaults to today)

##### search_with_time
Searches lifelogs with natural language time references:
- query: Search query text
- timeReference: Natural language time reference (e.g., "yesterday", "last week")
- timezone: IANA timezone specifier
- limit: Maximum number of results to return
- includeContent: Whether to include content in results

⚙️ Configuration

Limitless MCP can be configured using environment variables:

$3

- LIMITLESS_API_KEY: Your Limitless API key (required)
- LIMITLESS_API_BASE_URL: Limitless API base URL (default: "https://api.limitless.ai/v1")
- LIMITLESS_API_TIMEOUT_MS: Timeout in milliseconds for API calls (default: 120000)
- LIMITLESS_API_MAX_RETRIES: Maximum retries for failed API calls (default: 3)

$3

- LIMITLESS_MAX_LIFELOG_LIMIT: Maximum number of results per request (default: 100)
- LIMITLESS_DEFAULT_PAGE_SIZE: Default page size for listing results (default: 10)
- LIMITLESS_SEARCH_MULTIPLIER: Multiplier for search results retrieval (default: 3)

$3

- LIMITLESS_CACHE_TTL: Cache time-to-live in seconds (default: 300)
- LIMITLESS_CACHE_CHECK_PERIOD: Cache cleanup interval in seconds (default: 600)
- LIMITLESS_CACHE_MAX_KEYS: Maximum number of items in cache (default: 500)
- CACHE_TTL_METADATA: TTL multiplier for metadata (default: 3)
- CACHE_TTL_LISTINGS: TTL multiplier for listings (default: 2)
- CACHE_TTL_SEARCH: TTL multiplier for search results (default: 1.5)
- CACHE_TTL_SUMMARIES: TTL multiplier for summaries (default: 4)

$3

- LIMITLESS_PLUGINS_ENABLED: Set to "false" to disable all plugins
- LIMITLESS_PLUGIN_CONTENT_PROCESSOR: Set to "false" to disable the Content Processor plugin
- LIMITLESS_PLUGIN_DECORATOR: Set to "false" to disable the Decorator plugin
- LIMITLESS_DECORATOR_TEMPLATES: JSON string with custom templates
- LIMITLESS_PLUGIN_SEMANTIC_SEARCH: Set to "false" to disable the Semantic Search plugin
- LIMITLESS_SEMANTIC_SEARCH_TTL: TTL for embeddings cache in seconds (default: 3600)
- LIMITLESS_SEMANTIC_SEARCH_MAX_KEYS: Maximum number of embeddings to cache (default: 1000)
- LIMITLESS_PLUGIN_TIME_PARSER: Set to "false" to disable the Time Parser plugin
- LIMITLESS_DEFAULT_TIMEZONE: Default timezone for time parsing (default: "UTC")

For more details on plugin configuration, see plugins.md.

🛠️ Development

$3

`bash


Clone the repository

git clone https://github.com/jakerains/limitless-mcp.git
cd limitless-mcp

Install dependencies

npm install

Build the project

npm run build

Run in development mode with auto-reload

LIMITLESS_API_KEY="your-api-key" npm run dev

Or start the production server

LIMITLESS_API_KEY="your-api-key" npm start
`

$3

To test with a locally running instance:

`json
{
"mcpServers": {
"limitless-mcp": {
"command": "node",
"args": ["/path/to/limitless-mcp/dist/main.js"],
"env": {
"LIMITLESS_API_KEY": "your-api-key-here"
}
}
}
}
`

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

- Limitless AI for their incredible Pendant device and API
- Model Context Protocol team for creating the standard
- All contributors and users of this project

---

Made with ❤️ for enhancing AI interactions with your personal data