Obsidian Knowledge MCP

一个只读的 Obsidian 到 PostgreSQL 导入器和 MCP 服务器。笔记库是唯一事实来源：导入过程读取 Markdown 文件，绝不编辑或删除它们。

架构

Obsidian vault -> Python parser/upsert importer -> PostgreSQL -> FastMCP tools/resources -> Claude Connector

文档保留其相对路径和原始 Markdown 正文。每条笔记成为一个 document 节点；[[links]] 成为有向的 related_to 边和 document_links。标签、别名、标题和无法识别的 frontmatter 都保留在 JSONB 中。缺失的链接目标会被记录并跳过。重新运行导入会按文件路径更新记录，并防止重复的边/标签。

Related MCP server: Semantic Notes Vault MCP

设置

要求：Python 3.11+、Docker Desktop，以及一个 PostgreSQL 客户端（仅当你想手动检查 SQL 时）。

1. 将 .env.example 复制为 .env，设置 POSTGRES_PASSWORD，并将 OBSIDIAN_VAULT_PATH 设置为现有的笔记库。除非你愿意，否则不要将笔记库放在此项目内。

2. 创建环境并安装依赖：

   py -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -e ".[test]"

3. 启动 PostgreSQL。端口仅绑定到 localhost：

   docker compose up -d postgres

4. 导入笔记库：

   python -m ingestion.importer
   # or: obsidian-ingest "C:\path\to\vault"

5. 验证：

   docker compose exec postgres psql -U knowledge_app -d knowledge -c "select count(*) from documents; select count(*) from edges;"
   pytest

schema 作为初始化脚本挂载。对于已有的卷，请使用 psql -f database/schema.sql 显式应用更改。

在 Render 上部署

本仓库包含用于 Render 免费 Web Service 的 render.yaml。在 Render 中，从此仓库创建一个新的 Blueprint 并部署它。Render 将生成 MCP_AUTH_TOKEN 并使用其 PORT。由于 Render 要求为其托管的 PostgreSQL 服务提供支付信息，请从诸如 Neon 或 Supabase 之类的免费外部 PostgreSQL 提供商获取 DATABASE_URL。在查询之前，将 database/schema.sql 应用到该数据库。默认的公共端点是：

https://obsidian-knowledge-mcp.onrender.com/mcp

如果更改服务名称，请将 Render 环境中的 MCP_PUBLIC_URL 更新为生成的 https://<service-name>.onrender.com URL。不要在 MCP_PUBLIC_URL 中添加 /mcp；/mcp 只属于 Claude 连接器 URL。

Render 服务无法读取 Windows 或 OneDrive 上的笔记库。请从一台既能访问笔记库又能访问数据库的机器上将笔记库导入外部 PostgreSQL 数据库，或者在查询之前添加一个 Render 可访问的存储/导入作业。

MCP 服务器

本地运行方式：

python -m mcp_server.server

默认端点是 http://127.0.0.1:8000/mcp，使用 Streamable HTTP。对于本地客户端，设置 MCP_TRANSPORT=stdio，并使用 obsidian-mcp 作为命令。服务器提供 search_knowledge、get_node、get_document、get_related_nodes、find_path、list_nodes 和 search_documents 工具，以及 knowledge://node/{node_name} 资源。限制上限为 100，SQL 参数化。

Claude 连接器

Claude 连接器需要一个可从远程访问的 MCP 端点，而不是 PostgreSQL 端点。在 Claude 设置 -> 连接器中，添加以 /mcp 结尾的 Render URL，例如 https://obsidian-knowledge-mcp.onrender.com/mcp。当提示时，使用生成的 MCP_AUTH_TOKEN 作为 bearer token，完成你的 Claude 工作区所要求的身份验证流程，然后用 What do I have in my knowledge base about Python? 进行测试。

对于生产环境，请使用身份感知代理（OAuth/OIDC）或 mTLS，而不是静态令牌。不要暴露 5432 端口。如果 Claude 报告连接错误，请检查 docker compose ps、docker compose logs postgres、MCP 进程日志、HTTPS 证书/DNS、代理对 /mcp 的转发，以及该端点是否可从网络外部访问。将经过身份验证的健康检查与数据库错误分开，并且不要暴露堆栈跟踪。

示例查询

• 哪些概念与机器学习相关？

• 查找 Python 与人工智能之间的关系路径。

• 哪些概念在 RAG 的两跳范围之内？

• 哪些文档同时提到 Python 和机器学习？

假设与扩展点

此工作区中没有可供检查的笔记库，因此解析遵循标准的 Obsidian 约定，并由 tests/test_parser.py 中的测试夹具覆盖。Dataview 特有的语法将作为内容保留。仓库层将 SQL 与 MCP 隔离，从而在不更改 MCP 契约的情况下实现未来的双向同步。MCP_AUTH_TOKEN 由 Streamable HTTP 服务器强制执行；请使用身份感知代理（OAuth/OIDC）来加强生产环境访问控制。