内容
<div align="center">
# 🧠 Obsidian Everywhere
**将您的Obsidian知识库作为图谱，呈现在每个Claude客户端中。**
[](https://github.com/junnnnnw00/obsidian-everywhere/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
[](tsconfig.json)
[](https://modelcontextprotocol.io)
[](CONTRIBUTING.md)
*本地Claude代码 · Claude桌面版 · 通过Tailscale远程连接 · claude.ai网页和移动端 — 一个服务器，所有界面。*
</div>
---
**这是一个图谱服务器，而不是Markdown文件服务器。** Claude不应该将您的知识库视为一堆`.md`文件 — 它应该将笔记和链接视为一个图谱：支持反向链接遍历、n步邻域和以主题为中心的上下文包，这些都是首要工具，而不是在文件读取器上附加的后续功能。未解析的链接保留在图谱中（这是一个关于您知识库的真实信号，就像Obsidian本身一样），每个响应都为LLM实际需要的内容而结构化 — 明确的链接关系，而不仅仅是原始文本。
## 目录
- [功能](#功能)
- [它实际运行在哪里？](#它实际运行在哪里？)
- [快速入门](#快速入门)
- [配置](#配置)
- [开发](#开发)
- [项目状态](#项目状态)
- [贡献](#贡献)
- [许可证](#许可证)
## 功能
```
知识库（.md文件）
│ 解析 · 监视
▼
SQLite索引（FTS5） ⇄ 内存图谱（graphology）
│ n-hop · 最短路径 · PageRank
▼
14个MCP工具
│
▼
stdio · 带Bearer Token的HTTP · OAuth HTTP
```
- 🧩 **真正的图谱引擎** — Markdown解析器（wikilinks、embeds、frontmatter、嵌套标签、标题、块引用），带有全文搜索的SQLite索引，以及用于n-hop遍历、最短路径和PageRank的内存[graphology](https://graphology.github.io/)层 — 增量保持同步，因为文件会发生变化，永远不会从头重建。
- 🛠️ **14个图谱原生的MCP工具** — 12个只读，2个可写。
- 🔌 **三种连接方式** — 用于本地Claude客户端的stdio，具有静态Bearer Token的可流式HTTP用于远程Claude Code over Tailscale，以及具有OAuth 2.1（PKCE +动态客户端注册）的可流式HTTP用于claude.ai自定义连接器。
<details>
<summary><strong>完整工具列表</strong></summary>
**只读**
| 工具 | 功能 |
|---|---|
| `vault_overview` | 笔记数量、热门标签、PageRank中心节点、最近修改 — 一个起始导航 |
| `search_notes` | 带有标签/文件夹过滤器的全文搜索，每个结果都带有链接数量和标签注释 |
| `read_note` | 完整的笔记 + 图谱上下文头部（出链/入链/标签/前置信息）；可选的标题范围读取 |
| `get_backlinks` | 每个链接到给定笔记的笔记，带有链接句子 |
| `get_neighborhood` | 给定笔记周围的显式n-hop节点/边列表（链接视为无向） |
| `get_context_bundle` | **关键功能。** 以令牌预算打包中心笔记 + 优先1-hop邻居 |
| `list_tags` | 带有数量的全嵌套标签层次结构 |
| `get_notes_by_tag` | 携带给定标签的笔记（嵌套感知） |
| `find_orphans` | 没有入链或出链的笔记 |
| `find_unresolved` | 不解析为任何笔记的链接，按目标分组 |
| `find_path` | 两个笔记之间的最短连接路径，每个跳跃都有一个单行摘要 |
| `get_related` | *尚未* 直接链接的相似笔记（基于共享标签/邻居的Jaccard相似度） |
**可写**
| 工具 | 功能 |
|---|---|
| `create_note` | 创建一个新笔记（带有前置信息）；立即重新索引 — 下一个工具调用已经看到它 |
| `append_to_note` | 追加到笔记中，可选地在特定标题下；如果标题未找到，则关闭失败 |
`create_note`/`append_to_note`在stdio和带Bearer Token的HTTP传输上默认启用，在公共OAuth连接器传输上默认禁用（通过`OAUTH_ENABLE_WRITE_TOOLS=true`启用） — 参见[配置](#配置)和DECISIONS.md D15。
</details>
参见[`docs/architecture.md`](docs/architecture.md)了解其构建方式，参见[`docs/deploy.md`](docs/deploy.md)了解完整的部署拓扑（LaunchAgent、Docker、Cloudflare Tunnel）。
## 它实际运行在哪里？
**`obsidian-everywhere`进程需要直接的文件系统访问您的知识库的`.md`文件** （解析它们，监视更改等） — 因此它必须始终在**您的知识库物理驻留的机器上运行**（“知识库机器”：您的笔记本电脑，很可能）。您从哪里输入`claude`无关紧要 — *服务器*始终在知识库机器上运行；只有*客户端*连接方法会发生变化。
| 您从哪里运行`claude` | 您需要什么 |
|---|---|
| 与知识库相同的机器 | **stdio.** 无需其他 — Claude Code/Desktop直接启动服务器。 |
| 不同的您控制的机器（实验室/工作服务器，另一台笔记本电脑，SSH盒） | **带Bearer Token的HTTP** + 两台机器之间的私有网络（我们推荐[Tailscale](https://tailscale.com/download) — 免费，五分钟设置，无需端口转发即可跨NAT/防火墙工作）。 |
| claude.ai（网页应用或移动应用） | **OAuth HTTP** + 公共HTTPS URL（通过[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)）。claude.ai在Anthropic的云中运行，不在您的网络中，因此无法访问Tailscale或`localhost` — 它需要一个真正的公共地址。 |
您可以同时运行多个（例如，在笔记本电脑上运行stdio，在工作服务器上运行带Bearer Token的HTTP） — 它们是独立的进程，都索引相同的知识库。
## 快速入门
在**知识库机器**上运行（无论您的`.md`文件位于哪里）：
```bash
git clone https://github.com/junnnnnw00/obsidian-everywhere.git
cd obsidian-everywhere
npm install
npm run build
```
### 选项A — Claude Code，与知识库相同的机器（stdio）
仍在知识库机器上：
```bash
claude mcp add obsidian-everywhere -- node "$(pwd)/dist/cli.js" /path/to/your/vault
```
或使用环境变量代替位置参数：
```bash
OBSIDIAN_VAULT_PATH=/path/to/your/vault claude mcp add obsidian-everywhere -- node "$(pwd)/dist/cli.js"
```
### 选项A′ — Claude Desktop，与知识库相同的机器
将以下内容添加到知识库机器上的`claude_desktop_config.json`中：
```json
{
"mcpServers": {
"obsidian-everywhere": {
"command": "node",
"args": ["/absolute/path/to/obsidian-everywhere/dist/cli.js", "/absolute/path/to/your/vault"]
}
}
}
```
### 选项A″ — Google Antigravity CLI（agy）
将以下内容添加到您的全局Antigravity MCP配置文件（`~/.gemini/config/mcp_config.json`）：
```json
{
"mcpServers": {
"obsidian-everywhere": {
"command": "node",
"args": ["/absolute/path/to/obsidian-everywhere/dist/cli.js", "/absolute/path/to/your/vault"]
}
}
}
```
### 选项B — 在**不同**机器上运行Claude Code（实验室/工作服务器等）
**步骤1 — 在两台机器之间建立私有网络**，如果您还没有的话。最简单的选项是Tailscale：
```bash
# 在知识库机器和您将运行`claude`的机器上
curl -fsSL https://tailscale.com/install.sh | sh # 或：brew install tailscale（macOS）
tailscale up # 打开浏览器登录/加入您的“tailnet”
tailscale status # 确认两台机器都可以看到对方
```
从`tailscale status`中获取知识库机器的Tailscale主机名/IP（类似于`my-macbook.tailnet-name.ts.net`或`100.x.y.z`）。
**步骤2 — 在知识库机器上启动服务器：**
```bash
OBSIDIAN_VAULT_PATH=/path/to/vault OBSIDIAN_EVERYWHERE_TOKEN=$(openssl rand -hex 32) \
node dist/http-cli.js
```
保存此令牌 — 您将在步骤3中使用它。（要持久运行此命令，而不是在前台终端中运行，请参见[`docs/deploy.md`](docs/deploy.md#2-remote-claude-code-over-tailscale-static-bearer-token)中的LaunchAgent设置，或使用`docker-compose.yml`在Docker中运行它，如果知识库机器是服务器。）
**步骤3 — 从**其他**机器（实验室服务器等 — 实际输入`claude`的位置）使用知识库机器的Tailscale地址（步骤1）连接：
```bash
claude mcp add --transport http obsidian-everywhere \
http://<vault-machine-tailscale-name>:3737/mcp \
--header "Authorization: Bearer <步骤2中的令牌>"
```
就这样 — 第二台机器上的`claude`现在可以访问在第一台机器上索引的知识库。完整演练（Docker，LaunchAgent）：[`docs/deploy.md`](docs/deploy.md#2-remote-claude-code-over-tailscale-static-bearer-token).
### 选项C — claude.ai网页/移动应用（自定义连接器，OAuth）
这需要一个公共的HTTPS端点 — claude.ai的服务器无法访问您的Tailscale网络或`localhost`。参见[`docs/deploy.md`](docs/deploy.md#3-claudeai-webmobile-custom-connector-oauth-21--cloudflare-tunnel)获取完整的Cloudflare Tunnel演练（包括无需域的Quick Tunnel选项用于测试）。一旦您的服务器在`https://your-domain`可访问：
1. claude.ai → 设置 → 连接器 → 添加自定义连接器
2. 服务器网址：`https://your-domain/mcp`
3. claude.ai自动发现OAuth流程并显示此服务器的登录页面 — 输入您配置的`OAUTH_LOGIN_SECRET`。
**您仅在需要claude.ai的网页/移动应用读取您的知识库时才需要此操作。** 如果您只使用Claude Code（本地或从另一台机器），请完全跳过此操作 — 选项A/B已经完全涵盖了，无需Cloudflare/OAuth。
## 配置
| 环境变量 | 使用者 | 含义 |
|---|---|---|
| `OBSIDIAN_VAULT_PATH` | 所有 | 知识库路径（或作为命令行参数传递） |
| `OBSIDIAN_EVERYWHERE_DB` | 所有 | SQLite索引路径（默认：`<vault>/.obsidian-everywhere/index.db`） |
| `OBSIDIAN_EVERYWHERE_TOKEN` | `http-cli.js` | 静态Bearer令牌 |
| `PORT` | `http-cli.js`，`oauth-http-cli.js` | HTTP端口（默认为3737 / 3738） |
| `OAUTH_ISSUER_URL` | `oauth-http-cli.js` | 公共HTTPS源（例如您的Cloudflare Tunnel主机名） |
| `OAUTH_LOGIN_SECRET` | `oauth-http-cli.js` | 单用户登录秘密 |
| `OBSIDIAN_EVERYWHERE_READONLY` | `cli.js`，`http-cli.js` | 设置为`true`以禁用`create_note`/`append_to_note`（默认：写入工具开启） |
| `OAUTH_ENABLE_WRITE_TOOLS` | `oauth-http-cli.js` | 设置为`true`以在公共连接器上启用`create_note`/`append_to_note`（默认：关闭） |
## 开发
```bash
npm run dev:stdio # tsx，无构建步骤
npm run dev:http
npm run dev:oauth-http
npm test # vitest，针对fixtures/test-vault运行
npm run typecheck
npm run lint
npm run format:check
```
`fixtures/test-vault/`是一个30+笔记的固定知识库，锻炼了解析器需要处理的每个链接和解析边缘情况（管道别名，标题和块链接，嵌入，前置元数据嵌入的wikilinks，嵌套标签，跨文件夹的重复文件名，未解析的链接，代码块排除和韩文文件名/标签/ wikilinks）。这是`src/**/*.test.ts`中的每个测试运行的测试对象。
## 项目状态
v0.1，功能完整：完整的图谱引擎，所有三种传输（stdio，带Bearer Token的HTTP，OAuth HTTP），14个MCP工具，包括写入工具。少数事情需要有人完成（注册claude.ai连接器，实际的Cloudflare Tunnel帐户）因为它们需要浏览器/帐户 — 参见`docs/deploy.md`。针对固定知识库和具有韩文内容的真实58笔记个人知识库进行了测试。
## 贡献
欢迎提交错误报告，功能请求和PR — 参见[`CONTRIBUTING.md`](CONTRIBUTING.md)获取开发设置，测试约定以及固定知识库与测试套件的关系。安全问题：请参见[`SECURITY.md`](SECURITY.md)而不是公开问题。
## 许可证
MIT — 参见[`LICENSE`](LICENSE)。
