proofgeist/granola-mcp-server

GranolaAI MCP Server

🎙️ AI-Powered Meeting Intelligence for Claude Desktop

An experimental Model Context Protocol (MCP) server that bridges Granola.ai meeting intelligence with Claude Desktop. Access your meeting transcripts, notes, and insights directly through natural language conversations.

✨ 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
• 🔒 100% Local Processing — No external API calls; all data stays on your machine

🏗️ Architecture

flowchart TB
    subgraph Client["👤 Client Layer"]
        CD[Claude Desktop]
    end
    
    subgraph MCP["🔌 MCP Protocol Layer"]
        MCP_STDIO[MCP stdio Transport]
    end
    
    subgraph Server["⚙️ Granola MCP Server"]
        GMCS[GranolaMCPServer]
        
        subgraph Handlers["Request Handlers"]
            LIST[list_tools]
            CALL[call_tool]
        end
        
        subgraph Tools["Available Tools"]
            SEARCH[search_meetings]
            DETAILS[get_meeting_details]
            TRANSCRIPT[get_meeting_transcript]
            DOCS[get_meeting_documents]
            ANALYZE[analyze_meeting_patterns]
        end
        
        subgraph Cache["Cache Management"]
            LOAD[_load_cache]
            PARSE[_parse_cache_data]
            EXTRACT[_extract_document_panel_content]
        end
    end
    
    subgraph Data["💾 Data Layer"]
        CACHE_FILE[(Granola Cache<br/>cache-v4.json)]
        MODELS[Pydantic Models<br/>MeetingMetadata<br/>MeetingDocument<br/>MeetingTranscript]
    end
    
    CD -->|stdio| MCP_STDIO
    MCP_STDIO -->|MCP Protocol| GMCS
    GMCS --> LIST
    GMCS --> CALL
    CALL --> SEARCH
    CALL --> DETAILS
    CALL --> TRANSCRIPT
    CALL --> DOCS
    CALL --> ANALYZE
    GMCS --> LOAD
    LOAD --> PARSE
    PARSE --> EXTRACT
    PARSE -->|reads| CACHE_FILE
    PARSE --> MODELS

Data Flow

sequenceDiagram
    participant User as 👤 User
    participant Claude as 🤖 Claude Desktop
    participant Server as ⚙️ MCP Server
    participant Cache as 💾 Granola Cache

    User->>Claude: "Search for meetings about quarterly planning"
    Claude->>Server: MCP: search_meetings(query)
    Server->>Cache: Read cache file
    Cache-->>Server: Raw JSON data
    Server->>Server: Parse & validate with Pydantic
    Server->>Server: Search across titles, participants, transcripts
    Server-->>Claude: Matching meetings with metadata
    Claude-->>User: Formatted meeting results

    User->>Claude: "Get transcript from yesterday's meeting"
    Claude->>Server: MCP: get_meeting_transcript(id)
    Server->>Server: Lookup transcript in cache
    Server-->>Claude: Full transcript with speakers
    Claude-->>User: Readable conversation format

🛠️ Tech Stack

📦 Installation

Prerequisites

• uv package manager
• macOS with Granola.ai installed

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "granola": {
      "command": "uvx",
      "args": ["granola-mcp-server"]
    }
  }
}

Then restart Claude Desktop.

Claude Code

claude mcp add granola -- uvx granola-mcp-server

Cursor

Updating

uvx caches the package after first run. To update to the latest version:

uvx --refresh granola-mcp-server

Then restart your MCP client.

Manual installation (alternative)

If you prefer to install from source:

cd ~
git clone https://github.com/proofgeist/granola-mcp-server
cd granola-mcp-server
uv sync

Then configure your MCP client to run the server directly:

{
  "mcpServers": {
    "granola": {
      "command": "uv",
      "args": ["--directory", "/Users/YOUR_USERNAME/granola-mcp-server", "run", "granola-mcp-server"]
    }
  }
}

To update a source install: git pull && uv sync

pip (alternative)

pip install granola-mcp-server

Then configure your MCP client to run granola-mcp-server.

Environment Variables

Set GRANOLA_PARSE_PANELS=0 to disable document panel parsing if you encounter issues.

🚀 Usage

Once configured, restart Claude Desktop and start interacting with your Granola meetings using natural language:

Search & Discovery

• "Search for meetings about quarterly planning"
• "Show me yesterday's meetings"
• "Find meetings with David from this week"
• "List all my recent standup meetings"

Transcript Access

• "Get the transcript from yesterday's IA meeting"
• "What was discussed in the Float rollback planning meeting?"
• "Show me the full conversation from the David Tanner 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"

Available Tools

🧪 Development

Running Tests

# Run panel parsing test
uv run python test_server.py

# Test with real cache file
uv run python test_real_cache.py

Running the Server Directly

uv run granola-mcp-server

Or using the run script:

uv run python run_server.py

Project Structure

granola-mcp-server/
├── granola_mcp_server/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server implementation (~750 lines)
│   └── models.py            # Pydantic data models
├── .github/
│   └── workflows/
│       └── release.yml      # Semantic release automation
├── tests/
│   ├── test_server.py       # Unit tests with synthetic cache
│   └── test_real_cache.py   # Integration tests with real data
├── pyproject.toml           # Python package configuration + semantic-release config
├── run_server.py            # Entry point wrapper
├── INSTALL.md               # Detailed installation guide
├── LICENSE                  # MIT License
└── README.md                # This file

🔒 Security & Privacy

📊 Performance

• 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
• Production Ready: Successfully processes real Granola data (11.7MB cache files)
• Scalable: Handles large datasets with 500+ transcript segments per meeting

🐛 Troubleshooting

Common Issues

"Cache file not found"

# Ensure Granola.ai is installed and has processed some meetings
ls -la ~/Library/Application\ Support/Granola/cache-v*.json

"uv command not found"

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

Server not appearing in Claude Desktop

• Check Claude Desktop logs: ~/Library/Logs/Claude/mcp-server-granola.log
• Restart Claude Desktop after config changes

Meeting notes appear empty

• Granola sometimes stores rich notes inside documentPanels rather than notes_plain
• This server reads those panels by default; set GRANOLA_PARSE_PANELS=0 to disable

Manual installation issues

These apply only if you installed from source (git clone) rather than via uvx.

"Permission denied" or "Operation not permitted"

• This happens when the server is installed in ~/Documents or other protected macOS folders
• Move the installation to your home directory:

  mv ~/Documents/granola-mcp-server ~/granola-mcp-server
  cd ~/granola-mcp-server
  uv sync
  

  Then update the path in claude_desktop_config.json
• Or grant Claude Desktop Full Disk Access in System Settings > Privacy & Security

"Current directory does not exist"

• This error occurs when using uv run with the --directory flag
• Ensure the path in your Claude config points to the actual clone location

"Failed to spawn process" or "No such file or directory"

• Run uv sync in the project directory to rebuild the venv
• Verify the script exists: ls -la ~/granola-mcp-server/.venv/bin/granola-mcp-server

🤝 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 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.

📄 License

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

Copyright (c) 2025 Proof+Geist

🙏 Acknowledgments

• Granola.ai for the amazing meeting intelligence app
• Anthropic for Claude and the Model Context Protocol
• Astral for the uv package manager

⚠️ Disclaimer: This is an experimental project. Granola's cache format may change without notice. Use at your own risk.