# Granola MCP Server (Experimental)
An experimental Model Context Protocol (MCP) server for integrating Granola.ai meeting intelligence with Claude Desktop. This uses Granola's local cache. I don't have any idea how Granola updates or maintains that cache. My guess is that it's doing a rolling context window, but storing long term notes up in AWS. So, YMMV. Use at your own risk. I will likely add a cache shipper at some point since we don't have access to Gronala's data in the cloud.
## Features
- **Meeting Search**: Search meetings by title, content, participants, and transcript content
- **Meeting Details**: Get comprehensive meeting metadata with local timezone display
- **Full Transcript Access**: Retrieve complete meeting conversations with speaker identification
- **Rich Document Content**: Access actual meeting notes, summaries, and structured content
- **Pattern Analysis**: Analyze patterns across meetings (participants, frequency, topics)
- **Timezone Intelligence**: All timestamps automatically display in your local timezone
- **Real-time Integration**: Seamlessly connects to your actual Granola meeting data
## Quick Start
### Prerequisites
- Python 3.12+
- [uv](https://docs.astral.sh/uv/) package manager
- macOS with Granola.ai installed
- Claude Desktop application
- Granola cache file at `~/Library/Application Support/Granola/cache-v3.json`
### Installation
1. **Clone the repository to your home directory:**
```bash
cd ~
git clone <repository-url>
cd granola-ai-mcp-server
```
**Important:** Clone to your home directory (`~`) rather than `~/Documents` to avoid macOS permission issues with Claude Desktop.
2. **Install dependencies with uv:**
```bash
uv sync
```
3. **Test the installation:**
```bash
uv run python test_server.py
```
4. **Configure Claude Desktop** by adding to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"granola": {
"command": "/Users/YOUR_USERNAME/granola-ai-mcp-server/.venv/bin/granola-mcp-server",
"args": [],
"env": {}
}
}
}
```
**Important:**
- Replace `YOUR_USERNAME` with your actual macOS username
- Use the direct path to the virtual environment's script (not `uv run`) to avoid working directory issues
- The path should point to your home directory installation
5. **Restart Claude Desktop** to load the MCP server:
```bash
# Quit Claude completely
osascript -e 'quit app "Claude"'
# Reopen Claude
open -a "Claude"
```
## Available Tools
### search_meetings
Search meetings by query string.
```
Parameters:
- query (string): Search query for meetings
- limit (integer, optional): Maximum number of results (default: 10)
```
### get_meeting_details
Get detailed information about a specific meeting.
```
Parameters:
- meeting_id (string): Meeting ID to retrieve details for
```
### get_meeting_transcript
Get transcript for a specific meeting.
```
Parameters:
- meeting_id (string): Meeting ID to get transcript for
```
### get_meeting_documents
Get documents associated with a meeting.
```
Parameters:
- meeting_id (string): Meeting ID to get documents for
```
### analyze_meeting_patterns
Analyze patterns across multiple meetings.
```
Parameters:
- pattern_type (string): Type of pattern to analyze ('topics', 'participants', 'frequency')
- date_range (object, optional): Date range for analysis with start_date and end_date
```
## Usage Examples
Once configured with Claude Desktop, you can use natural language to interact with your Granola meetings:
### Basic Queries
- "Search for meetings about quarterly planning"
- "Show me yesterday's meetings"
- "Find meetings with David from this week"
### Transcript Access
- "Get the transcript from yesterday's ProofChat meeting"
- "What was discussed in the Float rollback planning meeting?"
- "Show me the full conversation from the David Tibbi meeting"
### Content Analysis
- "Analyze participant patterns from last month"
- "What documents are associated with the product review meeting?"
- "Search for mentions of 'schema labeling' in meeting transcripts"
### Recent Meeting Intelligence
The server automatically detects and provides access to:
- **Full transcripts** from recent meetings (25,000+ characters)
- **Meeting content** including notes and summaries
- **Participant information** and speaker identification
- **Local timezone display** for all meeting times
## Development
### Running Tests
```bash
uv run python test_server.py
```
### Running the Server Directly
```bash
uv run granola-mcp-server
```
### Adding Dependencies
```bash
uv add package-name
```
## Configuration
### Claude Desktop Config Locations
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
### Granola Cache Location
The server reads from Granola's cache file at:
```
~/Library/Application Support/Granola/cache-v3.json
```
## Security & Privacy
- ✅ **100% Local Processing** - All data stays on your machine
- ✅ **No External API Calls** - No data sent to external services
- ✅ **Granola Permissions Respected** - Uses existing Granola.ai access controls
- ✅ **Read-Only Access** - Server only reads from Granola's cache
## Performance & Capabilities
- **Fast Loading**: Sub-2 second cache loading for hundreds of meetings
- **Rich Content**: Extracts 25,000+ character transcripts and meeting notes
- **Efficient Search**: Multi-field search across titles, content, participants, and transcripts
- **Memory Optimized**: Lazy loading with intelligent content parsing
- **Timezone Smart**: Automatic local timezone detection and display
- **Production Ready**: Successfully processes real Granola data (11.7MB cache files)
- **Scalable**: Handles large datasets with 500+ transcript segments per meeting
## Current Status
🚀 **PRODUCTION READY** - Successfully tested with real Granola.ai data including:
- ✅ **39+ meetings** parsed and searchable
- ✅ **28 full transcripts** with complete conversations
- ✅ **Rich meeting content** from notes, summaries, and structured data
- ✅ **Timezone intelligence** showing times like "17:04" instead of "21:04 UTC"
- ✅ **Speaker identification** and conversation flow
- ✅ **Yesterday's meetings** fully accessible with detailed content
## Troubleshooting
### Common Issues
**"Cache file not found"**
- Ensure Granola.ai is installed and has processed some meetings
- Check that the cache file exists: `ls -la "~/Library/Application Support/Granola/cache-v3.json"`
**"uv command not found"**
- Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Or use pip fallback in Claude config: `"command": "python"`
**"Permission denied" or "Operation not permitted"**
- **Most common issue on macOS**: This happens when the server is installed in `~/Documents` or other protected folders
- **Solution 1 (Recommended)**: Move the installation to your home directory:
```bash
mv ~/Documents/granola-ai-mcp-server ~/granola-ai-mcp-server
cd ~/granola-ai-mcp-server
uv sync # Rebuild venv with correct paths
```
Then update the path in `claude_desktop_config.json`
- **Solution 2**: Grant Claude Desktop Full Disk Access:
1. Open System Settings → Privacy & Security → Full Disk Access
2. Click the lock icon and authenticate
3. Click "+" and add `/Applications/Claude.app`
4. Toggle Claude to "On"
5. Restart Claude Desktop
**"Current directory does not exist"**
- This error occurs when using `uv run` with the `--directory` flag
- Use the direct path to the venv script instead (see Installation step 4)
**Server not appearing in Claude Desktop**
- Verify the absolute path in your Claude config
- Check Claude Desktop logs: `~/Library/Logs/Claude/mcp-server-granola.log`
- Look for Python errors in the logs
- Ensure the path doesn't contain spaces or special characters
- Restart Claude Desktop after config changes
**"Failed to spawn process" or "No such file or directory"**
- The Python shebang in the venv script points to the wrong location
- Run `uv sync` in the project directory to rebuild the venv
- Verify the script exists: `ls -la ~/granola-ai-mcp-server/.venv/bin/granola-mcp-server`
### Meeting notes appear empty in Claude
- Granola sometimes stores rich notes inside `documentPanels` rather than `notes_plain`
- This server now reads those panels by default; set `GRANOLA_PARSE_PANELS=0` in the environment to disable
- Run `python test_real_cache.py` to verify that panel-backed notes produce content
