Skip to content
Back to search

granola-mcp-server

Local granola-ai-mcp-server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/proofsh--granola-mcp-server/badge.svg)](/listings/proofsh--granola-mcp-server)

HTML

<a href="/listings/proofsh--granola-mcp-server"><img src="/api/listings/proofsh--granola-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- [uv](https://docs.astral.sh/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

| Variable | Description | Default | |----------|-------------|---------| | `GRANOLA_PARSE_PANELS` | Enable parsing of document panels for rich notes | `1` (enabled) | | `TZ` | Override local timezone detection | Auto-detected |

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 370 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # GranolaAI MCP Server
  2. [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![MCP](https://img.shields.io/badge/MCP-1.0+-green.svg)](https://modelcontextprotocol.io/)
  5. > 🎙️ **AI-Powered Meeting Intelligence for Claude Desktop**
  6. An experimental [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that bridges [Granola.ai](https://granola.ai/) meeting intelligence with Claude Desktop. Access your meeting transcripts, notes, and insights directly through natural language conversations.
  7. ## ✨ Features
  8. - **🔍 Meeting Search** — Search meetings by title, content, participants, and transcript content
  9. - **📋 Meeting Details** — Get comprehensive meeting metadata with local timezone display
  10. - **📝 Full Transcript Access** — Retrieve complete meeting conversations with speaker identification
  11. - **📄 Rich Document Content** — Access actual meeting notes, summaries, and structured content
  12. - **📊 Pattern Analysis** — Analyze patterns across meetings (participants, frequency, topics)
  13. - **🌍 Timezone Intelligence** — All timestamps automatically display in your local timezone
  14. - **🔒 100% Local Processing** — No external API calls; all data stays on your machine
  15. ## 🏗️ Architecture
  16. ```mermaid
  17. flowchart TB
  18. subgraph Client["👤 Client Layer"]
  19. CD[Claude Desktop]
  20. end
  21. subgraph MCP["🔌 MCP Protocol Layer"]
  22. MCP_STDIO[MCP stdio Transport]
  23. end
  24. subgraph Server["⚙️ Granola MCP Server"]
  25. GMCS[GranolaMCPServer]
  26. subgraph Handlers["Request Handlers"]
  27. LIST[list_tools]
  28. CALL[call_tool]
  29. end
  30. subgraph Tools["Available Tools"]
  31. SEARCH[search_meetings]
  32. DETAILS[get_meeting_details]
  33. TRANSCRIPT[get_meeting_transcript]
  34. DOCS[get_meeting_documents]
  35. ANALYZE[analyze_meeting_patterns]
  36. end
  37. subgraph Cache["Cache Management"]
  38. LOAD[_load_cache]
  39. PARSE[_parse_cache_data]
  40. EXTRACT[_extract_document_panel_content]
  41. end
  42. end
  43. subgraph Data["💾 Data Layer"]
  44. CACHE_FILE[(Granola Cache<br/>cache-v*.json)]
  45. MODELS[Pydantic Models<br/>MeetingMetadata<br/>MeetingDocument<br/>MeetingTranscript]
  46. end
  47. CD -->|stdio| MCP_STDIO
  48. MCP_STDIO -->|MCP Protocol| GMCS
  49. GMCS --> LIST
  50. GMCS --> CALL
  51. CALL --> SEARCH
  52. CALL --> DETAILS
  53. CALL --> TRANSCRIPT
  54. CALL --> DOCS
  55. CALL --> ANALYZE
  56. GMCS --> LOAD
  57. LOAD --> PARSE
  58. PARSE --> EXTRACT
  59. PARSE -->|reads| CACHE_FILE
  60. PARSE --> MODELS
  61. ```
  62. ### Data Flow
  63. ```mermaid
  64. sequenceDiagram
  65. participant User as 👤 User
  66. participant Claude as 🤖 Claude Desktop
  67. participant Server as ⚙️ MCP Server
  68. participant Cache as 💾 Granola Cache
  69. User->>Claude: "Search for meetings about quarterly planning"
  70. Claude->>Server: MCP: search_meetings(query)
  71. Server->>Cache: Read cache file
  72. Cache-->>Server: Raw JSON data
  73. Server->>Server: Parse & validate with Pydantic
  74. Server->>Server: Search across titles, participants, transcripts
  75. Server-->>Claude: Matching meetings with metadata
  76. Claude-->>User: Formatted meeting results
  77. User->>Claude: "Get transcript from yesterday's meeting"
  78. Claude->>Server: MCP: get_meeting_transcript(id)
  79. Server->>Server: Lookup transcript in cache
  80. Server-->>Claude: Full transcript with speakers
  81. Claude-->>User: Readable conversation format
  82. ```
  83. ## 🛠️ Tech Stack
  84. | Component | Technology |
  85. |-----------|------------|
  86. | **Language** | Python 3.12+ |
  87. | **MCP SDK** | `mcp>=1.0.0` |
  88. | **Data Validation** | Pydantic 2.x |
  89. | **Package Manager** | uv (recommended) or pip |
  90. | **Build System** | Hatchling |
  91. | **Release Automation** | python-semantic-release |
  92. ## 📦 Installation
  93. ### Prerequisites
  94. - [uv](https://docs.astral.sh/uv/) package manager
  95. - macOS with Granola.ai installed
  96. ### Claude Desktop
  97. Add to your `claude_desktop_config.json`:
  98. **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  99. ```json
  100. {
  101. "mcpServers": {
  102. "granola": {
  103. "command": "uvx",
  104. "args": ["granola-mcp-server"]
  105. }
  106. }
  107. }
  108. ```
  109. Then restart Claude Desktop.
  110. ### Claude Code
  111. ```bash
  112. claude mcp add granola -- uvx granola-mcp-server
  113. ```
  114. ### Cursor
  115. [![Add Granola MCP to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=granola&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJncmFub2xhLW1jcC1zZXJ2ZXIiXSwiZW52Ijp7fX0=)
  116. ### Updating
  117. `uvx` caches the package after first run. To update to the latest version:
  118. ```bash
  119. uvx --refresh granola-mcp-server
  120. ```
  121. Then restart your MCP client.
  122. ### Manual installation (alternative)
  123. If you prefer to install from source:
  124. ```bash
  125. cd ~
  126. git clone https://github.com/proofgeist/granola-mcp-server
  127. cd granola-mcp-server
  128. uv sync
  129. ```
  130. Then configure your MCP client to run the server directly:
  131. ```json
  132. {
  133. "mcpServers": {
  134. "granola": {
  135. "command": "uv",
  136. "args": ["--directory", "/Users/YOUR_USERNAME/granola-mcp-server", "run", "granola-mcp-server"]
  137. }
  138. }
  139. }
  140. ```
  141. To update a source install: `git pull && uv sync`
  142. ### pip (alternative)
  143. ```bash
  144. pip install granola-mcp-server
  145. ```
  146. Then configure your MCP client to run `granola-mcp-server`.
  147. ### Environment Variables
  148. | Variable | Description | Default |
  149. |----------|-------------|---------|
  150. | `GRANOLA_PARSE_PANELS` | Enable parsing of document panels for rich notes | `1` (enabled) |
  151. | `TZ` | Override local timezone detection | Auto-detected |
  152. Set `GRANOLA_PARSE_PANELS=0` to disable document panel parsing if you encounter issues.
  153. ## 🚀 Usage
  154. Once configured, restart Claude Desktop and start interacting with your Granola meetings using natural language:
  155. ### Search & Discovery
  156. - *"Search for meetings about quarterly planning"*
  157. - *"Show me yesterday's meetings"*
  158. - *"Find meetings with David from this week"*
  159. - *"List all my recent standup meetings"*
  160. ### Transcript Access
  161. - *"Get the transcript from yesterday's IA meeting"*
  162. - *"What was discussed in the Float rollback planning meeting?"*
  163. - *"Show me the full conversation from the David Tanner meeting"*
  164. ### Content Analysis
  165. - *"Analyze participant patterns from last month"*
  166. - *"What documents are associated with the product review meeting?"*
  167. - *"Search for mentions of 'schema labeling' in meeting transcripts"*
  168. ### Available Tools
  169. | Tool | Description | Parameters |
  170. |------|-------------|------------|
  171. | `search_meetings` | Search meetings by title, content, participants | `query` (string), `limit` (int, optional) |
  172. | `get_meeting_details` | Get detailed information about a meeting | `meeting_id` (string) |
  173. | `get_meeting_transcript` | Get full transcript with speaker identification | `meeting_id` (string) |
  174. | `get_meeting_documents` | Get documents and notes associated with a meeting | `meeting_id` (string) |
  175. | `analyze_meeting_patterns` | Analyze patterns across meetings | `pattern_type` (enum: topics/participants/frequency), `date_range` (optional) |
  176. ## 🧪 Development
  177. ### Running Tests
  178. ```bash
  179. # Run panel parsing test
  180. uv run python test_server.py
  181. # Test with real cache file
  182. uv run python test_real_cache.py
  183. ```
  184. ### Running the Server Directly
  185. ```bash
  186. uv run granola-mcp-server
  187. ```
  188. Or using the run script:
  189. ```bash
  190. uv run python run_server.py
  191. ```
  192. ### Project Structure
  193. ```
  194. granola-mcp-server/
  195. ├── granola_mcp_server/
  196. │ ├── __init__.py # Package initialization
  197. │ ├── server.py # Main MCP server implementation (~750 lines)
  198. │ └── models.py # Pydantic data models
  199. ├── .github/
  200. │ └── workflows/
  201. │ └── release.yml # Semantic release automation
  202. ├── tests/
  203. │ ├── test_server.py # Unit tests with synthetic cache
  204. │ └── test_real_cache.py # Integration tests with real data
  205. ├── pyproject.toml # Python package configuration + semantic-release config
  206. ├── run_server.py # Entry point wrapper
  207. ├── INSTALL.md # Detailed installation guide
  208. ├── LICENSE # MIT License
  209. └── README.md # This file
  210. ```
  211. ## 🔒 Security & Privacy
  212. | Feature | Status |
  213. |---------|--------|
  214. | **100% Local Processing** | ✅ All data stays on your machine |
  215. | **No External API Calls** | ✅ No data sent to external services |
  216. | **Granola Permissions Respected** | ✅ Uses existing Granola.ai access controls |
  217. | **Read-Only Access** | ✅ Server only reads from Granola's cache |
  218. ## 📊 Performance
  219. - **Fast Loading**: Sub-2 second cache loading for hundreds of meetings
  220. - **Rich Content**: Extracts 25,000+ character transcripts and meeting notes
  221. - **Efficient Search**: Multi-field search across titles, content, participants, and transcripts
  222. - **Memory Optimized**: Lazy loading with intelligent content parsing
  223. - **Production Ready**: Successfully processes real Granola data (11.7MB cache files)
  224. - **Scalable**: Handles large datasets with 500+ transcript segments per meeting
  225. ## 🐛 Troubleshooting
  226. ### Common Issues
  227. **"Cache file not found"**
  228. ```bash
  229. # Ensure Granola.ai is installed and has processed some meetings
  230. ls -la ~/Library/Application\ Support/Granola/cache-v*.json
  231. ```
  232. **"uv command not found"**
  233. ```bash
  234. # Install uv
  235. curl -LsSf https://astral.sh/uv/install.sh | sh
  236. ```
  237. **Server not appearing in Claude Desktop**
  238. - Check Claude Desktop logs: `~/Library/Logs/Claude/mcp-server-granola.log`
  239. - Restart Claude Desktop after config changes
  240. **Meeting notes appear empty**
  241. - Granola sometimes stores rich notes inside `documentPanels` rather than `notes_plain`
  242. - This server reads those panels by default; set `GRANOLA_PARSE_PANELS=0` to disable
  243. ### Manual installation issues
  244. These apply only if you installed from source (git clone) rather than via `uvx`.
  245. **"Permission denied" or "Operation not permitted"**
  246. - This happens when the server is installed in `~/Documents` or other protected macOS folders
  247. - Move the installation to your home directory:
  248. ```bash
  249. mv ~/Documents/granola-mcp-server ~/granola-mcp-server
  250. cd ~/granola-mcp-server
  251. uv sync
  252. ```
  253. Then update the path in `claude_desktop_config.json`
  254. - Or grant Claude Desktop Full Disk Access in System Settings > Privacy & Security
  255. **"Current directory does not exist"**
  256. - This error occurs when using `uv run` with the `--directory` flag
  257. - Ensure the path in your Claude config points to the actual clone location
  258. **"Failed to spawn process" or "No such file or directory"**
  259. - Run `uv sync` in the project directory to rebuild the venv
  260. - Verify the script exists: `ls -la ~/granola-mcp-server/.venv/bin/granola-mcp-server`
  261. ## 🤝 Contributing
  262. Contributions are welcome! Please feel free to submit a Pull Request.
  263. 1. Fork the repository
  264. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  265. 3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
  266. 4. Push to the branch (`git push origin feature/amazing-feature`)
  267. 5. Open a Pull Request
  268. Please ensure your code follows the existing style and includes appropriate tests.
  269. ## 📄 License
  270. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  271. Copyright (c) 2025 [Proof+Geist](https://proofgeist.com/)
  272. ## 🙏 Acknowledgments
  273. - [Granola.ai](https://granola.ai/) for the amazing meeting intelligence app
  274. - [Anthropic](https://anthropic.com/) for Claude and the Model Context Protocol
  275. - [Astral](https://astral.sh/) for the uv package manager
  276. ---
  277. > ⚠️ **Disclaimer**: This is an experimental project. Granola's cache format may change without notice. Use at your own risk.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.