Nexus MCP

🚀 Nexus MCP

Nexus MCP 是一个强大的个人助理 MCP 服务器，它集成了包括谷歌日历、Obsidian 知识库、Trello 等多种服务，还具备网页解析能力。该服务器基于 FastMCP 构建，为管理你的数字生活提供了统一的接口。

🚀 快速开始

Nexus MCP 服务器搭建完成后，将为你提供一个集成化的数字生活管理平台，让你可以便捷地管理日历、笔记、Trello 看板等。以下是使用该服务器的基本步骤：

1. 启动服务器：

poetry run python main.py

2. 连接客户端：服务器启动后，即可接受 MCP 兼容客户端的连接。
3. 使用工具：借助任何 MCP 兼容客户端与服务器交互，服务器提供了以下工具：
   • 日历管理
   • Obsidian 知识库操作
   • Trello 看板管理
   • 网页解析

✨ 主要特性

• 谷歌日历集成
  • 创建、读取、更新和删除日历事件
  • 列出即将到来的事件
• Obsidian 知识库管理
  • 创建、读取、更新和删除笔记
  • 笔记全文搜索
  • 文件夹管理（创建、删除、搜索、列出）
• Trello 集成
  • 看板、列表和卡片管理
  • 创建、更新和删除卡片
  • 通过文本查询搜索卡片
• 网页解析
  • 从任何 URL 提取并清理 HTML 内容
• 谷歌新闻搜索
  • 搜索给定主题的近期新闻文章

📦 安装指南

前提条件

• Python 3.10 或更高版本
• Poetry（Python 包管理器）
• 谷歌日历 API 凭证
• Trello API 凭证（如果使用 Trello 功能）
• Obsidian 知识库（如果使用 Obsidian 功能）

安装步骤

1. 克隆仓库：

git clone https://github.com/yourusername/nexus-mcp.git
cd nexus-mcp

2. 使用 Poetry 安装依赖：

poetry install

3. 设置谷歌日历 API：
   • 访问 谷歌云控制台
   • 创建一个新项目或选择现有项目
   • 启用谷歌日历 API
   • 创建 OAuth 2.0 凭证
   • 下载凭证并保存为项目根目录下的 credentials.json
4. 设置 Trello API（可选）：
   • 访问 Trello 开发者门户
   • 获取你的 API 密钥和令牌
   • 将它们添加到环境变量或配置文件中

💻 使用示例

基础用法

启动服务器：

poetry run python main.py

高级用法

若要将此服务器与 Anthropic Claude Desktop 配合使用，请在你的 Claude Desktop 设置中添加以下配置：

{
   "mcpServers": {
      "personal-assistant": {
         "command": "/path/to/your/venv/bin/python",
         "args": ["/path/to/your/project/main.py"],
         "env": {
                 "GOOGLE_CREDENTIALS_PATH": "/path/to/your/credentials.json",
                 "GOOGLE_TOKEN_PATH": "/path/to/your/token.json",
                 "GOOGLE_API_KEY": "your_google_api_key",
                 "GOOGLE_CX_ID": "your_google_cx_id",
                 "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
                 "OBSIDIAN_DEFAULT_FOLDER": "your_default_folder",
                 "TRELLO_API_KEY": "your_trello_api_key",
                 "TRELLO_TOKEN": "your_trello_token",
                 "LOG_PATH": "/path/to/log.txt",
                 "ENABLE_OBSIDIAN_TOOLS": "True/False",
                 "ENABLE_TRELLO_TOOLS": "True/False",
                 "ENABLE_CALENDAR_TOOLS": "True/False",
                 "ENABLE_NEWS_SEARCH": "True/False",
                 "ENABLE_WEB_PARSER": "True/False",
                 "SEMANTIC_SEARCH_ENABLED": "True/False",
                 "EMBEDDINGS_PATH": "/path/to/embeddings.json"
         }
      }
   }
}

请将路径和凭证替换为你自己的实际值：

• command：Python 虚拟环境的 Python 可执行文件路径
• args：项目的 main.py 文件路径
• ENABLE_OBSIDIAN_TOOLS：设置为 True 以启用 Obsidian 工具
• ENABLE_TRELLO_TOOLS：设置为 True 以启用 Trello 工具
• ENABLE_CALENDAR_TOOLS：设置为 True 以启用谷歌日历工具
• ENABLE_NEWS_SEARCH：设置为 True 以启用谷歌新闻搜索
• ENABLE_WEB_PARSER：设置为 True 以启用网页解析工具
• GOOGLE_CREDENTIALS_PATH：谷歌日历凭证文件（credentials.json）的路径
• GOOGLE_TOKEN_PATH：谷歌日历令牌文件（token.json）的路径
• GOOGLE_API_KEY：你的谷歌 API 密钥（用于自定义搜索 API）
• GOOGLE_CX_ID：你的谷歌可编程搜索引擎 ID（自定义搜索 API 的 CX ID）
• OBSIDIAN_VAULT_PATH：Obsidian 知识库的路径
• OBSIDIAN_DEFAULT_FOLDER：可选，知识库中创建新笔记的默认文件夹路径
• TRELLO_API_KEY：你的 Trello API 密钥
• TRELLO_TOKEN：你的 Trello API 令牌
• LOG_PATH：日志文件的路径
• SEMANTIC_SEARCH_ENABLED：设置为 True 以启用 Obsidian 知识库的语义搜索
• SIMILARITY_TRESHOLD：默认值为 0.5，这是语义搜索的阈值
• EMBEDDINGS_PATH：可选，Obsidian 向量搜索插件生成的嵌入 JSON 文件的路径（如果未设置，默认为相对于 OBSIDIAN_VAULT_PATH 的 .obsidian/plugins/vector-search/data.json）
• MODEL_TOKEN_LIMIT：AI 模型理解笔记分块的限制
• CHUNK_SIZE_TOKENS：分块大小

若要启用语义搜索功能，你需要为 Obsidian 安装 向量搜索插件。 重新索引过程完成后，插件将在以下位置生成一个包含向量嵌入的 JSON 文件：

.obsidian/plugins/vector-search/data.json

该文件将作为语义搜索查询的嵌入源。

📚 详细文档

推荐客户端

• Anthropic Claude Desktop
• 5ire

开发相关

• 项目使用 Poetry 进行依赖管理。
• 所有工具都在 main.py 中注册。
• 特定服务的实现位于 services/ 目录中。
• Python 代码遵循 PEP 8 风格指南。

贡献指南

1. 分叉仓库。
2. 创建你的功能分支（git checkout -b feature/amazing-feature）。
3. 提交你的更改（git commit -m 'Add some amazing feature'）。
4. 推送到该分支（git push origin feature/amazing-feature）。
5. 打开一个拉取请求。

同时，你可以加入 Telegram 和 博客 与开发者交流。