# Obsidian OneDrive MCP Server

OneDrive 上の Obsidian Vault に、MCP クライアントから Markdown ノートを読み書きするリモート対応サーバーです。

PC のローカル同期フォルダを直接操作するのではなく、常時稼働できるサーバーから Microsoft Graph API で OneDrive に書き込みます。そのため、自宅PCがオフラインでもノートを作成でき、PCを起動した時に通常の OneDrive 同期で Obsidian Vault に反映されます。

```text
MCP client
    │ HTTPS + Bearer key
    ▼
Always-on MCP server
    │ Microsoft Graph
    ▼
OneDrive / Obsidian Vault
    │ OneDrive sync (when the PC is online)
    ▼
Obsidian on the PC
```

## 機能

- `write_markdown`: ノートの新規作成、上書き、追記
- `read_markdown`: ノートの読み込み
- `list_markdown`: フォルダ内のノート一覧（再帰検索対応）
- 存在しないノート用フォルダの自動作成
- ETag による同時編集の競合検出
- Vault 外へのパストラバーサル、`.obsidian`、Markdown 以外へのアクセスを拒否
- MCP 2026-07-28 と、2025系クライアント向け stateless Streamable HTTP に対応
- 個人用 OneDrive のデバイスコード認証とトークン自動更新
- 組織用 OneDrive のクライアント資格情報認証
- stdio モード（ローカル利用・デバッグ用）

## 必要なもの

- Node.js 22 以上、または Docker
- OneDrive に同期している既存の Obsidian Vault
- Microsoft Entra のアプリ登録
- リモート利用時は HTTPS を終端できるリバースプロキシまたはホスティングサービス

## 個人用 OneDrive のセットアップ

個人用 Microsoft アカウントでは、デバイスコードで一度サインインし、更新トークンを永続ディスクに保存する方式を使います。

1. [Microsoft Entra admin center](https://entra.microsoft.com/) でアプリを登録します。
2. 対応するアカウントの種類に「個人用 Microsoft アカウント」を含めます。
3. 「認証」→「詳細設定」から、パブリック クライアント フローを有効にします。
4. Microsoft Graph の委任されたアクセス許可 `Files.ReadWrite` を追加します。
5. 設定ファイルを作ります。

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

最低限、次の値を編集してください。

```dotenv
MICROSOFT_TENANT_ID=consumers
MICROSOFT_CLIENT_ID=登録したアプリのクライアントID
MICROSOFT_TOKEN_FILE=./data/tokens.json
ONEDRIVE_VAULT_PATH=Documents/Obsidian/MyVault

MCP_API_KEY=十分に長いランダム値
MCP_ALLOWED_HOSTS=localhost,127.0.0.1,mcp.example.com
```

`ONEDRIVE_VAULT_PATH` はローカルパスではなく、OneDrive ルートから見たパスです。

6. 依存関係を入れ、Microsoft アカウントを認証します。

```bash
npm install
npm run auth:device
```

画面に表示されたURLとコードでサインインすると、`MICROSOFT_TOKEN_FILE` にトークンが保存されます。このファイルはパスワードと同様に扱い、Gitへ追加しないでください。

7. サーバーを起動します。

```bash
npm run dev
```

認証とVaultパスを確認できます。

```bash
curl -H "Authorization: Bearer $MCP_API_KEY" http://localhost:3000/ready
```

## Docker で実行

```bash
cp .env.example .env
docker compose build
docker compose run --rm obsidian-mcp node dist/device-auth.js
docker compose up -d
```

更新トークンは `obsidian-mcp-data` ボリュームに保存されます。クラウドへ配置する場合も、`/app/data` に永続ディスクを接続した上で、その環境のシェルからデバイス認証を一度実行してください。コンテナイメージやGitリポジトリにトークンを含めてはいけません。

永続ディスクや対話シェルを提供しないホスティングでは、次の組織アカウント方式を使うか、トークンを安全に永続化できる基盤を選んでください。

## 組織用 OneDrive の無人認証

Microsoft 365 の組織テナントでは、クライアント資格情報を使用できます。アプリに Microsoft Graph のアプリケーション権限 `Files.ReadWrite.All` を追加し、管理者の同意を与えます。その上で次を設定します。

```dotenv
MICROSOFT_TENANT_ID=組織のテナントID
MICROSOFT_CLIENT_ID=クライアントID
MICROSOFT_CLIENT_SECRET=クライアントシークレット
ONEDRIVE_USER_ID=user@example.com
ONEDRIVE_VAULT_PATH=Documents/Obsidian/MyVault
```

`ONEDRIVE_DRIVE_ID` が分かる場合は、`ONEDRIVE_USER_ID` の代わり、または併用で指定できます。アプリケーション権限は対象範囲が広いため、専用アカウントやMicrosoft Graphの選択的アクセス許可も検討してください。

## MCP クライアントから接続

MCP エンドポイントは次のURLです。

```text
https://mcp.example.com/mcp
```

HTTPヘッダーを設定できるMCPクライアントに、次を指定します。

```json
{
  "url": "https://mcp.example.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_MCP_API_KEY"
  }
}
```

クライアントごとに設定形式は異なります。インターネットへ公開する場合、`MCP_API_KEY` に加えて必ずHTTPSを使用してください。

## ツールの挙動

### `write_markdown`

```json
{
  "path": "Inbox/new-idea",
  "content": "# New idea\n\nDetails...",
  "mode": "create"
}
```

`path` の `.md` は省略できます。`mode` は次の3種類です。

- `create`: 既存ノートがあれば失敗します。既定値です。
- `overwrite`: 既存ノートを置き換えます。
- `append`: 既存ノートの末尾に追記します。存在しなければ新規作成します。

上書き・追記中にOneDrive上のノートが変更された場合は競合エラーを返します。内容を読み直してから、再度実行してください。

### `read_markdown`

```json
{ "path": "Inbox/new-idea.md" }
```

### `list_markdown`

```json
{
  "folder": "Inbox",
  "recursive": true,
  "limit": 100
}
```

## stdio モード

同じマシン上でMCPクライアントから子プロセスとして起動する場合に利用できます。ただし、この方式はそのマシンが起動している時だけ動作します。

```bash
npm run build
npm run start:stdio
```

## 開発

```bash
npm install
npm run typecheck
npm test
npm run build
```

## セキュリティ上の注意

- `.env`、クライアントシークレット、`tokens.json` をGitへ追加しないでください。
- `MCP_API_KEY` は長いランダム値にし、漏えい時は交換してください。
- `MCP_ALLOWED_HOSTS` には実際に使うホスト名だけを指定してください。
- ブラウザから接続する場合だけ `MCP_ALLOWED_ORIGINS` に許可するOriginのホスト名を指定してください。
- 本番環境ではHTTPSを使い、MCPサーバーを直接平文でインターネットへ公開しないでください。
- サーバーは設定されたVault配下のMarkdownだけを扱いますが、Microsoft Graph側の権限も可能な限り小さくしてください。

## References

- [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Microsoft Graph: upload or replace the contents of a driveItem](https://learn.microsoft.com/en-us/graph/api/driveitem-put-content?view=graph-rest-1.0)
- [Microsoft identity platform device authorization grant](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-device-code)

## License

[MIT](./LICENSE)

---

English summary: this is a remote-capable MCP server that writes Markdown directly to an Obsidian vault in OneDrive through Microsoft Graph. The Obsidian machine does not need to remain powered on; it receives changes later through normal OneDrive sync.