# Obsidian & Google Drive MCP Server 🚀

[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Streamable%20HTTP%20%7C%20SSE-green.svg)](https://modelcontextprotocol.io/)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B%20%7C%2022-brightgreen.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An All-in-One remote **Model Context Protocol (MCP)** server that connects **Google Gemini Web**, **Claude Desktop**, **Cursor**, and other AI clients directly to your **Obsidian Vault** and personal **Google Drive**.

Built with dual-transport support (**Streamable HTTP** + **Legacy SSE**), **RFC 8414 OAuth 2.0 Discovery**, and an intelligent **Safe File Adoption Engine**.

---

## ✨ Features

- 🌐 **Dual Protocol Support:**
  - **Streamable HTTP (MCP 2025 Standard):** Direct `POST`, `GET`, and `DELETE` requests with session management for **Gemini Web** Connected Apps.
  - **Legacy SSE:** Server-Sent Events with `/messages` transport for **Claude Desktop**, **Cursor**, and older MCP clients.
- 🔐 **OAuth 2.0 Discovery (RFC 8414 & OpenID Connect):**
  - Automated discovery endpoints (`/.well-known/oauth-authorization-server`, `/.well-known/openid-configuration`, `/oauth/authorize`, `/oauth/token`).
  - Seamless authentication handshake without custom plugin configuration.
- 📁 **Dual-Token Architecture:**
  - **Remotely-Save Token (`drive.file` scope):** Reads and writes Obsidian Markdown notes cleanly within your vault directory, ensuring zero sync conflicts with the Obsidian Remotely-Save plugin.
  - **Personal Google Drive Token (`drive` scope):** Searches and reads any document, spreadsheet, or file across your entire personal Google Drive.
- 🛡️ **Safe File Adoption Engine:**
  - Automatically identifies files uploaded manually to Google Drive and converts them so the Obsidian Remotely-Save plugin recognizes and syncs them to your devices.
  - Built-in Mutex locks and streaming memory bounds prevent race conditions and out-of-memory errors.

---

## 🛠️ MCP Tools Included

| Tool Name | Scope | Description |
|---|---|---|
| `obsidian_list_vault` | Remotely-Save Vault | Recursively lists all markdown notes and directories inside your Obsidian Vault. |
| `obsidian_read_note` | Remotely-Save Vault | Reads the full Markdown content of a specific note (e.g., `Inbox/Ideas.md`). |
| `obsidian_write_note` | Remotely-Save Vault | Creates, overwrites, or appends (`append`) content to a note in your vault. |
| `obsidian_adopt_manual_files`| Dual Scope | Scans and safely adopts manually uploaded Drive files into Obsidian-compatible notes. |
| `gdrive_search_all` | Full Google Drive | Searches files and documents across your entire Google Drive by query or name. |
| `gdrive_read_document` | Full Google Drive | Reads Google Docs, Sheets, text, or Markdown files from anywhere on Google Drive. |

---

## 🔑 Prerequisites: Getting the Obsidian Remotely-Save Token

To enable bidirectional sync between this MCP server and your Obsidian Vault without sync conflicts, this server integrates directly with the [remotely-save](https://github.com/remotely-save/remotely-save) plugin:

1. **Install Remotely-Save in Obsidian:**
   - Open Obsidian → **Settings** → **Community plugins**.
   - Search for **Remotely Save** ([GitHub repository](https://github.com/remotely-save/remotely-save)) and click **Install** then **Enable**.
2. **Authenticate with Google Drive:**
   - In Remotely Save settings, select **Google Drive** as the sync provider.
   - Click **Authenticate** and complete the Google login to grant permission to your vault directory.
   - Run a manual sync once. Remotely Save will save the token in your vault at `.obsidian/plugins/remotely-save/data.json`.
3. **Token Usage Modes:**
   - **Local Mode (Zero-Config):**  
     If running this server on the same machine as your Obsidian Vault, the server automatically discovers and decodes the token from `~/Documents/<VAULT_NAME>/.obsidian/plugins/remotely-save/data.json`. You don't need to copy any tokens!
   - **Cloud Mode (Render.com / Docker):**  
     If deploying to the cloud, run this helper command on your local machine to extract your credentials:
     ```bash
     npm run export:remotely-save
     ```
     Then copy the output (`OBSIDIAN_CLIENT_ID`, `OBSIDIAN_CLIENT_SECRET`, `OBSIDIAN_REFRESH_TOKEN`) into your Render Environment Variables or `.env` file.

---

## 🚀 Quick Start

### 1. Clone & Install Dependencies

```bash
git clone https://github.com/hung301203/obsidian-gdrive-mcp.git
cd obsidian-gdrive-mcp
npm install
```

### 2. Configure Environment Variables

Copy the sample environment file:

```bash
cp .env.example .env
```

Edit `.env` with your settings:

```env
PORT=3000
MCP_API_KEY=your_secret_mcp_api_key_here
VAULT_FOLDER_NAME=your_obsidian_vault_folder_name # e.g. MyVault or Personal_Notes

# Full Google Drive OAuth credentials (optional for full drive search)
FULL_DRIVE_CLIENT_ID=your_client_id
FULL_DRIVE_CLIENT_SECRET=your_client_secret
FULL_DRIVE_REFRESH_TOKEN=your_refresh_token
```

> **Tip:** If running locally on a machine with Obsidian installed, the server automatically detects and decodes the Remotely-Save OAuth token from:  
> `~/Documents/<VAULT_NAME>/.obsidian/plugins/remotely-save/data.json`

### 3. Build & Run

```bash
# Build TypeScript
npm run build

# Start server
npm start
```

---

## ☁️ Cloud Deployment (Render.com)

Deploy free 24/7 on [Render](https://render.com):

1. Fork or push this repository to your GitHub account.
2. In Render Dashboard, click **New +** → **Blueprint** and connect your repository.
3. Render will read [`render.yaml`](render.yaml) automatically.
4. Fill in the environment variables when prompted (`MCP_API_KEY`, `VAULT_FOLDER_NAME`, etc.).
5. Once deployed, your public MCP server URL will be:
   ```text
   https://<your-subdomain>.onrender.com/mcp/<MCP_API_KEY>/sse
   ```

---

## 🔌 Connecting to AI Clients

### 1. Google Gemini Web (`gemini.google.com`)

1. Open **Gemini Web** → Settings → **Connected Apps** (or click **+ Custom**).
2. Under **MCP server URL**, enter:
   ```text
   https://<your-subdomain>.onrender.com/mcp/<MCP_API_KEY>/sse
   ```
3. Leave **Client ID** and **Client secret** blank (the API key is already authenticated in the URL).
4. Click **Connect** / **Next**. Gemini will connect via Streamable HTTP and expose all 6 tools.

### 2. Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "obsidian-gdrive": {
      "url": "https://<your-domain>.onrender.com/mcp/<MCP_API_KEY>/sse"
    }
  }
}
```

### 3. Cursor & Windsurf

In Cursor/Windsurf MCP Settings:
- **Type:** `sse`
- **URL:** `https://<your-domain>.onrender.com/mcp/<MCP_API_KEY>/sse`

---

## 🐳 Docker Deployment

Run with Docker Compose:

```bash
docker compose up -d --build
```

---

## 🧪 Testing

The test suite covers unit tests, memory limits, SSE heartbeats, and Streamable HTTP protocol compatibility:

```bash
npm test
```

---

## 📄 License

This project is open-source software licensed under the [MIT License](LICENSE).