MCP Etebase

Etebase MCP服务器

Etebase的综合模型上下文协议（MCP）服务器，提供对日历、任务、联系人和协作功能的完整访问。

目的

此MCP服务器为AI助手提供了一个安全的接口，用于管理您的自托管Etebase实例。支持端到端的加密个人信息管理，包括日历（VEVENT）、任务（VTODO）和联系人（VCARD）。

特性

API全面覆盖：58个工具（100%）

此服务器实现 100%的python-tebase API，分为6类：

工具类别

1.账户管理（11个工具）

管理身份验证、会话和帐户设置。

• account_save_session -将当前会话令牌保存到secrets文件
• account_logout -注销并使当前会话无效
• account_change_password -更改帐户密码（需要旧密码）
• account_fetch_token -获取并刷新身份验证令牌
• account_force_server_url -更改服务器终结点URL
• account_login -使用用户名和密码登录以创建新会话
• account_signup -创建新的Etebase帐户
• account_is_etebase_server -验证URL是否是有效的Etebase服务器
• account_get_collection_manager -获取集合管理器实例信息
• account_get_invitation_manager -获取邀请管理器实例信息

2.收藏管理（13个工具）

创建和管理日历、任务列表和通讯簿。

• collections_list -按类型列出所有集合（etebase.vevent/vtodo/vcard）
• collection_create -使用名称、颜色和描述创建新收藏
• collection_get -按UID获取集合详细信息
• collection_update -更新集合元数据
• collection_delete -按UID删除集合
• collection_upload -将集合更改上载到服务器
• collection_create_raw -从原始加密数据创建（高级）
• collection_transaction -为批处理操作创建事务
• collection_verify -验证集合完整性
• collection_cache_save -将集合保存到本地缓存
• collection_cache_load -从缓存加载收集
• collection_get_item_manager -获取物品管理器进行收集
• collection_get_member_manager -获取成员经理以进行共享

3.项目管理（17个工具）

事件、任务和联系人的CRUD操作。

• items_list -列出集合中的所有项目
• item_create -使用原始iCalendar/vCard内容创建项目
• item_get -按UID获取项目内容
• item_update -用新内容更新项目
• item_delete -按UID删除项目
• item_upload_content -单独上传项目内容
• item_download_content -下载项目内容
• item_create_raw -从原始加密数据创建（高级）
• item_batch -执行批量操作
• item_fetch_multi -一次获取多个项目
• item_fetch_updates -获取增量更新（同步）
• item_revisions -获取修订历史记录
• item_transaction -为批处理操作创建事务
• item_verify -验证项目完整性
• item_cache_save -将项目保存到本地缓存
• item_cache_load -从缓存加载项目

4.分享与协作（4个工具）

共享收藏并管理成员权限。

• member_list -列出共享收藏的所有成员
• member_modify_access -更改成员权限（管理员/读写/只读）
• member_remove -从集合中删除成员
• member_leave -留下共享收藏

5.邀请函（7个工具）

邀请用户并管理邀请生命周期。

• invitation_invite -邀请用户加入收藏
• invitation_list_incoming -列出收到的邀请
• invitation_list_outgoing -列出已发送的邀请
• invitation_accept -接受邀请
• invitation_reject -拒绝邀请
• invitation_disinvite -取消已发送的邀请
• invitation_fetch_user_profile -获取邀请的用户配置文件

6.高级助手（3个工具）

简化了常见操作的界面。

• event_create -使用自动iCalendar格式创建日历事件
• task_create -使用自动VTODO格式化创建任务
• contact_create -使用自动vCard格式创建联系人

先决条件

• Python 3.11或更高版本
• pip（Python包安装程序）
• 克劳德代码CLI
• 带有存储会话令牌的自托管Etebase实例

安装

步骤1：安装依赖项

cd ~/.local/share/mcp-servers/mcp-etebase
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

步骤2：配置机密

确保您的Etebase凭据在 ~/.config/mcp-secrets.json:

{
  "etebase": {
    "server_url": "https://your-etebase-server.com",
    "username": "your-username",
    "stored_session": "your-stored-session-token"
  }
}

安全：确保适当的权限：

chmod 600 ~/.config/mcp-secrets.json

步骤3：配置Claude代码

服务器已在中配置 ~/.claude.json:

{
  "mcpServers": {
    "etebase": {
      "command": "python",
      "args": [
        "/home/YOUR_USERNAME/.local/share/mcp-servers/mcp-etebase/etebase_server.py"
      ],
      "env": {
        "VIRTUAL_ENV": "/home/YOUR_USERNAME/.local/share/mcp-servers/mcp-etebase/venv",
        "PATH": "/home/YOUR_USERNAME/.local/share/mcp-servers/mcp-etebase/venv/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

替换 YOUR_USERNAME 使用您的实际用户名。

使用示例

在Claude Code中，你可以问：

日历管理

• “列出我的所有日历”
• “创建一个名为“工作”的蓝色新日历”
• “明天下午2点创建一个名为“团队会议”的活动”

任务管理

• “列出我的所有任务列表”
• “在我的‘个人’列表中创建一个新任务：购买杂货”
• “显示本周到期的所有任务”

联系人管理

• “列出我的通讯簿”
• “添加新联系人：John Doe，john@example.com, 555-1234"

协作

• “显示我的‘家庭日历’成员”
• “邀请alice@example.com到我的“共享任务”集合
• “列出我的待处理邀请”

高级操作

• “同步来自服务器的日历更新”
• “显示此任务的修订历史记录”
• “验证我的地址簿的完整性”

建筑

Claude Code → Etebase MCP Server (Python venv) → Etebase Instance
                      ↓
      ~/.config/mcp-secrets.json
      (stored_session, server_url)

发展

局部测试

# Activate virtual environment
cd ~/.local/share/mcp-servers/mcp-etebase
source venv/bin/activate

# Test server startup
python etebase_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python etebase_server.py

添加新工具

1. 将该功能添加到 etebase_server.py
2. 用…装饰 @mcp.tool()
3. 仅使用单行文档字符串
4. 返回格式化字符串（从不复杂对象）
5. 重新启动Claude代码以重新加载

故障排除

工具未出现

• 验证虚拟环境是否已激活
• 检查 ~/.claude.json 路径正确
• 确保 etebase_server.py 具有执行权限
• 重新启动克劳德代码CLI

身份验证错误

• 在中验证机密 ~/.config/mcp-secrets.json
• 确保JSON语法有效
• 检查文件权限（应为600）
• 验证存储的会话令牌是否有效

连接问题

• 验证Etebase服务器URL是否可访问
• 检查网络连接
• 确保服务器支持API版本

与以前版本的比较

安全考虑

• 所有秘密都存储在 ~/.config/mcp-secrets.json
• 永远不要在源文件中硬编码凭据
• 文件权限仅限制用户访问（600）
• 从未记录敏感数据
• 由Etebase维护的端到端加密
• 会话令牌可以通过以下方式无效 account_logout

许可证

MIT许可证

学分

内置：

• FastMCP -MCP服务器框架
• python-etebase -Etebase Python客户端
• 埃特巴斯 -端到端加密后端