Bird MCP服务器

一个个人助理MCP（模型上下文协议）服务器，与Todoist、Anki和Obsidian集成，帮助您学习、组织和保持高效。使用Python和FastMCP构建，完全打包 uv 与Docker兼容。

快速参考

# Quick start with uv
uv venv && source .venv/bin/activate
uv pip install -e .
cp .env.example .env  # Edit with your API tokens
python -m bird_mcp.server

# Add to Claude Code
claude mcp add --transport stdio --scope local bird-personal-assistant -- python -m bird_mcp.server

# Build Docker image
docker build -t bird-mcp .

# Run with Docker
docker run -i --rm --env-file .env bird-mcp

特性

目前已实施

Todoist集成（11个工具）：

创建带有描述、截止日期、优先级和标签的任务
按项目、标签或自定义筛选器检索和筛选任务
完成、更新和删除任务
添加和检索任务的评论
分析任务统计数据（优先级分布、项目细分、截止日期）
列出所有项目、标签和部分

Anki集成（14个工具）：

创建和管理甲板
创建基本抽认卡（正面/背面）
创建完形填空删除卡
获取全面的统计数据（每层和整体）
更新甲板配置（每日限制）
使用Anki搜索语法查找笔记
暂停/取消暂停卡
获取笔记类型和详细的笔记信息
更新和删除笔记

黑曜石集成（8个工具）：

创建、阅读、更新和删除笔记
按内容、文件夹或标签搜索笔记
列出vault或特定文件夹中的注释
获取或创建每日笔记
获取保险库统计信息

谷歌日历集成（10个工具）：

列出所有可用日历
创建、更新和删除日历事件
获取时间范围内的事件（今天、即将发生、自定义）
查找用于日程安排的空闲时段
使用自然语言快速添加事件
为学习工作流程安排学习时间

健康检查：

监控所有集成服务的连接和状态

先决条件

Python 3.10或更高版本
紫外线（推荐）或pip
Docker（可选，用于容器化部署）
Todoist帐户和API令牌
带AnkiConnect插件的Anki（可选，用于Anki功能）
黑曜石拱顶（可选，用于黑曜岩特征）
带有OAuth2凭据的Google日历（可选，用于Google日历功能）

快速开始

1.获取您的API代币

Todoist API代币：

首选 Todoist集成
滚动到“API令牌”部分
复制您的API令牌

AnkiConnect设置（可选）：

打开安基
转到工具→ 附加组件→ 获取扩展
输入代码： 2055492159
重新启动Anki
AnkiConnect将在上运行 http://localhost:8765 默认情况下

谷歌日历设置（可选）： 看谷歌日历设置指南有关OAuth2配置的详细说明，请参阅下面的部分。

2.设置环境变量

创建一个 .env 项目根目录中的文件：

# Required
TODOIST_API_TOKEN=your_todoist_token_here

# Optional
ANKI_CONNECT_URL=http://localhost:8765
OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault
GOOGLE_CALENDAR_CREDENTIALS_PATH=/path/to/credentials.json

安装与运行

选项1：使用紫外线（推荐）

uv 是一个快速的Python包安装程序和解析器。该项目已完全配置为与 uv.

安装uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

安装依赖项

# Install all dependencies (including the package itself)
uv sync

# Or install in editable mode
uv pip install -e .

运行服务器

# Direct execution
uv run python -m bird_mcp.server

# Or using mcp CLI (for development with inspector)
uv run mcp dev src/bird_mcp/server.py

这 mcp dev 命令将启动MCP检查器 http://localhost:6274 用于测试和调试。

选项2：使用pip

创建虚拟环境

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

安装依赖项

pip install -r requirements.txt
pip install -e .

运行服务器

python -m bird_mcp.server

选项3：使用Docker

对黑曜石融合很重要： 如果你想在Docker中使用Obsidian功能，你需要将你的保管库作为卷挂载（见下文）。

使用Docker Compose构建和运行

# 1. Create .env file with your configuration
cp .env.example .env

# 2. Edit .env and configure:
#    - TODOIST_API_TOKEN (required)
#    - ANKI_CONNECT_URL (optional, default: http://host.docker.internal:8765)
#    - OBSIDIAN_VAULT_PATH (optional, for Obsidian integration)

# 3. Build and start the production container
docker-compose up -d

# Or start the development container with MCP Inspector
docker-compose --profile dev up -d bird-mcp-dev

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

安装黑曜石保险库（黑曜岩集成所需）

如果你想使用黑曜石功能，你需要将你的保险库装载到容器中。编辑 docker-compose.yml:

services:
  bird-mcp:
    # ... existing configuration
    volumes:
      # Mount your Obsidian vault (read-write access)
      - /path/to/your/obsidian/vault:/app/vault:rw
    environment:
      - TODOIST_API_TOKEN=${TODOIST_API_TOKEN}
      - ANKI_CONNECT_URL=${ANKI_CONNECT_URL:-http://host.docker.internal:8765}
      - OBSIDIAN_VAULT_PATH=/app/vault  # Path inside container

然后更新您的 .env:

# .env
OBSIDIAN_VAULT_PATH=/app/vault  # This matches the container path

注：这 host.docker.internal hostname允许Docker容器连接到主机上运行的AnkiConnect。

直接使用Docker构建和运行

# Build production image
docker build -t bird-mcp .

# Run production container (basic, no Obsidian)
docker run -d --name bird-mcp --env-file .env bird-mcp

# Run with Obsidian vault mounted
docker run -d --name bird-mcp \
  --env-file .env \
  -v /path/to/your/obsidian/vault:/app/vault:rw \
  -e OBSIDIAN_VAULT_PATH=/app/vault \
  bird-mcp

# Build development image (with MCP Inspector)
docker build -f Dockerfile.dev -t bird-mcp-dev .

# Run development container with all features
docker run -d --name bird-mcp-dev \
  --env-file .env \
  -p 6274:6274 -p 6277:6277 \
  -v /path/to/your/obsidian/vault:/app/vault:rw \
  -e OBSIDIAN_VAULT_PATH=/app/vault \
  bird-mcp-dev

# Access MCP Inspector at http://localhost:6274

在Claude Desktop中使用Docker

要在Claude Desktop中使用Docker化的MCP服务器，请在您的 claude_desktop_config.json:

{
  "mcpServers": {
    "bird": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/absolute/path/to/bird/.env",
        "-v",
        "/absolute/path/to/obsidian/vault:/app/vault:rw",
        "bird-mcp"
      ]
    }
  }
}

重要提示： 使用绝对路径 --env-file 以及音量安装。

包装

该项目已正确配置，可与两者打包 uv 以及遵循PEP 621标准的标准Python工具。

封装结构

该项目使用 src 布局以实现更好的包装实践：

bird/
├── src/
│   └── bird_mcp/
│       ├── __init__.py                 # Package initialization with version
│       ├── server.py                   # Main MCP server with tool registrations
│       ├── todoist_tools.py            # Todoist API integration (11 tools)
│       ├── anki_tools.py               # AnkiConnect API integration (14 tools)
│       ├── obsidian_tools.py           # Obsidian vault integration (8 tools)
│       ├── google_calendar_tools.py    # Google Calendar API integration (10 tools)
│       └── utils.py                    # Error handling and retry decorators
├── pyproject.toml                      # PEP 621 package configuration
├── requirements.txt                    # Dependencies list (for pip)
├── uv.lock                             # Locked dependencies (for uv reproducibility)
├── .dockerignore                       # Files excluded from Docker builds
├── Dockerfile                          # Production Docker image (uses uv)
├── Dockerfile.dev                      # Development Docker image (with MCP Inspector)
├── docker-compose.yml                  # Multi-service Docker configuration
├── .env.example                        # Example environment variables
└── README.md                           # This file

构建包

方法1：使用紫外线（推荐）

uv 是一个快速的Python包安装程序和解析器，提供更好的依赖关系管理和更快的构建。

# Install the package in editable mode (for development)
uv pip install -e .

# This allows you to modify source code and see changes immediately
# The package is installed but points to your source directory

# Build distribution packages
uv build

# This creates two distribution formats:
# - dist/bird_mcp-0.1.0.tar.gz        (source distribution)
# - dist/bird_mcp-0.1.0-py3-none-any.whl  (wheel - faster to install)

轮子里是什么？

编译的字节码(.pyc 文件）
来自的所有源模块 src/bird_mcp/
包元数据来自 pyproject.toml
依赖关系列表

方法2：使用pip和setuptools

# Install the package in editable mode
pip install -e .

# Install build tool
pip install build

# Build distribution packages
python -m build

# This creates the same dist/ files as uv build

从源安装

从本地目录安装

# For development (editable install - changes reflect immediately)
cd /path/to/bird
pip install -e .

# For production (regular install - creates a copy)
pip install /path/to/bird

# With uv
uv pip install -e /path/to/bird

从Git仓库安装

# Direct from git (requires git URL)
pip install git+https://github.com/yourusername/bird.git

# With uv
uv pip install git+https://github.com/yourusername/bird.git

# Specific branch or tag
pip install git+https://github.com/yourusername/bird.git@main

从内置车轮安装

# After building with 'uv build' or 'python -m build'
pip install dist/bird_mcp-0.1.0-py3-none-any.whl

# With uv
uv pip install dist/bird_mcp-0.1.0-py3-none-any.whl

发布到PyPI（未来）

当准备发布到PyPI进行公开分发时：

# 1. Ensure version is updated in pyproject.toml
# 2. Build fresh distribution packages
uv build

# 3. Check the distribution
twine check dist/*

# 4. Upload to TestPyPI first (for testing)
uv publish --publish-url https://test.pypi.org/legacy/

# 5. Test installation from TestPyPI
pip install -i https://test.pypi.org/simple/ bird-mcp

# 6. If everything works, publish to real PyPI
uv publish

# Users can then install with:
# pip install bird-mcp

验证安装

安装软件包后，验证其是否正常工作：

# Check package is installed
pip list | grep bird-mcp

# Check version
python -c "import bird_mcp; print(bird_mcp.__version__)"

# Run the MCP server
python -m bird_mcp.server

# You should see:
# INFO - Initializing Todoist integration...
# INFO - Todoist integration initialized successfully
# ...

依赖管理

该项目为不同的工具使用多个依赖文件：

pyproject.toml：依赖关系的真实来源（PEP 621）
需求.txt：由pip用户的pyproject.toml生成
uv.lock：锁定文件，用于使用uv进行可复制的构建

更新依赖关系

# With uv (recommended - updates uv.lock automatically)
uv add package-name
uv add --dev package-name  # for dev dependencies

# With pip (requires manual updates)
# 1. Edit pyproject.toml dependencies list
# 2. Reinstall
pip install -e .
# 3. Update requirements.txt
pip freeze > requirements.txt

同步依赖关系

# Install exact versions from uv.lock (reproducible)
uv sync --frozen

# Update all dependencies to latest compatible versions
uv sync

# Update a specific package
uv add package-name --upgrade

MCP客户端配置

Claude桌面/光标配置

要将此MCP服务器与Claude Desktop或Cursor一起使用，请将以下内容添加到MCP设置文件中：

地点：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

配置（直接使用Python）：

{
  "mcpServers": {
    "bird": {
      "command": "python",
      "args": ["-m", "bird_mcp.server"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here",
        "ANKI_CONNECT_URL": "http://localhost:8765",
        "OBSIDIAN_VAULT_PATH": "/path/to/vault"
      }
    }
  }
}

配置（使用紫外线）：

{
  "mcpServers": {
    "bird": {
      "command": "uv",
      "args": ["run", "python", "-m", "bird_mcp.server"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here",
        "ANKI_CONNECT_URL": "http://localhost:8765",
        "OBSIDIAN_VAULT_PATH": "/path/to/vault"
      }
    }
  }
}

配置（使用Docker）：

{
  "mcpServers": {
    "bird": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/path/to/.env",
        "bird-mcp"
      ]
    }
  }
}

注：更新配置文件后，重新启动Claude Desktop或Cursor以使更改生效。

Claude代码配置

要将此MCP服务器与Claude Code（CLI工具）一起使用，请使用 claude mcp add 命令：

快速设置

# Add the server to Claude Code with local scope
claude mcp add --transport stdio --scope local bird-personal-assistant -- python -m bird_mcp.server

# Or with uv
claude mcp add --transport stdio --scope local bird-personal-assistant -- uv run python -m bird_mcp.server

验证连接

# List all configured MCP servers
claude mcp list

# You should see:
# bird-personal-assistant: python -m bird_mcp.server - ✓ Connected

Claude代码的环境变量

克劳德代码将使用 .env 项目目录中的文件。确保其配置正确：

# Navigate to your project directory
cd /path/to/bird

# Create .env from example
cp .env.example .env

# Edit .env with your credentials
# Required:
TODOIST_API_TOKEN=your_token_here

# Optional:
ANKI_CONNECT_URL=http://localhost:8765
OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault

重要提示： 运行时确保您位于项目目录中 claude 命令，否则服务器将无法找到 .env 文件。

测试集成

配置后，您可以使用Claude Code测试服务器：

# Start a conversation
claude

# Try a command like:
"Check the health of my MCP server"
"Create a Todoist task named 'Test from Claude Code'"
"Show me my Obsidian vault statistics"

删除服务器

如果你需要从Claude Code中删除服务器：

# Remove the MCP server
claude mcp remove bird-personal-assistant

发展

项目架构

Bird MCP服务器采用模块化架构构建：

核心组件：

服务器.py -主MCP服务器

- 通过以下方式注册所有工具 @mcp.tool() 装饰器 - 初始化与环境变量的集成 - 处理工具执行和错误响应 - 提供健康检查端点

todoist_tools.py -Todoist集成

- 使用官方 todoist-api-python 图书馆 - 异步/等待模式 asyncio.to_thread() 用于同步API调用 - 处理结果分页器嵌套列表结构 - 11种任务管理和分析工具

ankitools.py -AnkiConnect集成

- AnkiConnect的HTTP API客户端（端口8765） - 卡片创建前的纸币类型验证 - 支持基本卡片、完形填空删除和卡片管理 - 14个闪卡操作工具

黑曜石工具.py -黑曜石融合

- 基于文件系统的保险存储访问（不需要API） - YAML frontmatter解析和生成 - 每日笔记集成 - 8个笔记管理工具

google_calendar_tools.py -谷歌日历集成

- 使用Google Calendar API v3进行OAuth2身份验证 - 自动令牌刷新和持久化 - 自然语言事件创建（快速添加） - 免费时段查找和学习时间限制 - 10个日历管理工具

utils.py -共享公用设施

- 错误处理装饰器以获得一致的响应 - 使用指数回退重试逻辑 - 用于未来集成的BaseIntegration抽象类

设计模式：

可选集成模式：如果不配置，服务将正常降级
错误处理：一致 {"success": bool, "error": str} 回应
异步/等待：外部API调用的非阻塞操作
基于环境的配置：所有秘密都通过环境变量

项目结构

bird/
├── src/
│   └── bird_mcp/
│       ├── __init__.py                 # Package initialization with version
│       ├── server.py                   # Main MCP server (44 tools total)
│       ├── todoist_tools.py            # Todoist API integration (11 tools)
│       ├── anki_tools.py               # AnkiConnect API integration (14 tools)
│       ├── obsidian_tools.py           # Obsidian vault integration (8 tools)
│       ├── google_calendar_tools.py    # Google Calendar API integration (10 tools)
│       └── utils.py                    # Error handling and retry decorators
├── Dockerfile                          # Production Docker image (uses uv)
├── Dockerfile.dev                      # Development Docker image (uses uv)
├── docker-compose.yml                  # Docker Compose configuration
├── .dockerignore                       # Files excluded from Docker builds
├── pyproject.toml                      # Package configuration (PEP 621)
├── requirements.txt                    # Dependencies list
├── uv.lock                             # Locked dependencies (uv)
├── .env.example                        # Example environment variables
└── README.md                           # This file

开发设置

# Clone the repository
git clone https://github.com/yourusername/bird.git
cd bird

# Create virtual environment with uv (recommended)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Or with Python's venv
python -m venv venv
source venv/bin/activate

# Install dependencies in editable mode
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

# Set up environment variables
cp .env.example .env
# Edit .env with your API tokens

# Run the server
python -m bird_mcp.server

添加新的MCP工具

要向服务器添加新的MCP工具，请执行以下步骤：

1.创建或更新工具实现

在单独的文件中创建新的工具类（例如。， src/bird_mcp/my_service_tools.py)或向现有工具类添加方法：

"""My Service integration tools."""

from typing import Any
import httpx

class MyServiceTools:
    """Tools for interacting with My Service API."""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.client = httpx.AsyncClient()
    
    async def do_something(self, param: str) -> dict[str, Any]:
        """Do something with the service.
        
        Args:
            param: Some parameter
            
        Returns:
            Dictionary with success status and result/error
        """
        try:
            # Your implementation here
            response = await self.client.get(
                "https://api.example.com/endpoint",
                headers={"Authorization": f"Bearer {self.api_key}"},
                params={"param": param}
            )
            response.raise_for_status()
            return {"success": True, "data": response.json()}
        except Exception as e:
            return {"success": False, "error": str(e)}

2.在server.py中初始化工具

在中添加初始化代码 src/bird_mcp/server.py:

# At the top with other imports
from bird_mcp.my_service_tools import MyServiceTools

# In the initialization section (around line 40-67)
my_service_key = os.getenv("MY_SERVICE_API_KEY")
my_service = None
if my_service_key:
    try:
        logger.info("Initializing My Service integration...")
        my_service = MyServiceTools(my_service_key)
        logger.info("My Service integration initialized successfully")
    except Exception as e:
        logger.warning(f"My Service integration disabled: {e}")
else:
    logger.info("My Service integration disabled (MY_SERVICE_API_KEY not set)")

3.在MCP注册工具

在中添加工具注册功能 src/bird_mcp/server.py:

# My Service Tools

@mcp.tool()
async def my_service_do_something(param: str) -> dict[str, Any]:
    """Do something with My Service.
    
    Args:
        param: Some parameter description
        
    Returns:
        Dictionary with success status and result
    """
    if not my_service:
        return {"success": False, "error": "My Service integration not configured"}
    
    return await my_service.do_something(param=param)

4.添加健康检查（可选）

更新 health_check 包含新服务的工具：

# In the health_check function (around line 73-148)
# Check My Service
if my_service:
    try:
        logger.info("Performing My Service health check...")
        result = await my_service.do_something("test")
        results["services"]["my_service"] = {
            "status": "connected" if result["success"] else "error",
            "message": (
                "Successfully connected to My Service"
                if result["success"]
                else result.get("error")
            ),
        }
    except Exception as e:
        logger.error(f"My Service health check failed: {e}")
        results["services"]["my_service"] = {"status": "error", "message": str(e)}
else:
    results["services"]["my_service"] = {
        "status": "disabled",
        "message": "My Service integration not configured (set MY_SERVICE_API_KEY)",
    }

5.更新依赖关系（如果需要）

如果您的新工具需要其他依赖项：

对于紫外线：

uv add package-name

对于pip：

pip install package-name
# Then update requirements.txt
pip freeze > requirements.txt

或手动添加到 pyproject.toml:

dependencies = [
    # ... existing dependencies
    "package-name>=1.0.0",
]

6.更新环境变量

将新服务的API密钥添加到 .env.example 并记录下来：

# .env.example
MY_SERVICE_API_KEY=your_api_key_here

7.测试你的工具

# Start the MCP server with inspector
uv run mcp dev src/bird_mcp/server.py

# Or run directly
uv run python -m bird_mcp.server

打开 http://localhost:6274 （如果使用 mcp dev)在MCP检查器中测试您的工具。

8.更新文档

将您的新工具添加到此README中的“可用工具”部分
更新顶部的功能列表
记录任何新的环境变量

运行测试

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# With coverage
pytest --cov=src/bird_mcp --cov-report=html

代码格式化

# Format code with black
black src/

# Lint code with ruff
ruff check src/

# Auto-fix linting issues
ruff check --fix src/

使用MCP Inspector进行开发

MCP Inspector是一个基于网络的工具，用于测试和调试MCP服务器：

# Start server with inspector
uv run mcp dev src/bird_mcp/server.py

# Or with Docker
docker-compose --profile dev up bird-mcp-dev

然后打开 http://localhost:6274 在您的浏览器中。您需要终端输出中显示的身份验证令牌。

可用工具

健康检查（1个工具）

健康检查：检查所有集成服务（Todoist、Anki、Obsidian、谷歌日历）的运行状况和连接性

Todoist工具（11个工具）

todoist_create_task：使用可选的描述、项目、截止日期、优先级和标签创建新任务
todoist_gets：使用可选筛选器（项目、标签）检索任务
todoist_complete_task：将任务标记为已完成
todoist_update_task：更新任务内容、描述、截止日期、优先级或标签
todoist_delete_task：永久删除任务
待办事项_分析_开始：获取有关任务的全面统计数据
todoist_get-projects：列出您的所有Todoist项目
todoist_getlabels：获取所有可用的Todoist标签
todoist_get-sections：获取部分，可选择按项目筛选
todoist_getcomments：获取任务的所有评论
todoist_add注释：向任务添加注释

Anki工具（14个工具）

anki_create_deck：在Anki中创建新甲板
anki_get_decks：获取所有Anki牌及其ID
anki_create_note：创建一个具有正面和背面的基本抽认卡
anki_create_clozenote：创建完形填空删除卡（例如，“{{c1:：Paris}}是{{c2:：France}}的首都”）
anki_get_deck_stats：获取特定牌组的统计数据（卡数、到期卡等）
anki_get_all_stats：获取所有平台的全面统计数据
anki_update_deck_config：更新卡片组设置（每天新卡，每天评论）
anki_find_notes：使用Anki搜索语法查找笔记（例如，“deck:法语标签：动词”）
anki_suped卡：暂停卡片，防止其出现在评论中
银行卡：取消使用卡片，让它们再次出现在评论中
anki_get_note_types：获取Anki中所有可用的钞票类型（型号）
anki_update_note：更新现有Anki笔记的字段和标签
anki_get_note_info：获取有关特定注释的详细信息
anki_delete_notes：从Anki中永久删除笔记

黑曜石工具（8工具）

黑曜石创造笔记：在黑曜石保管库中使用可选文件夹、标签和封面创建新笔记
黑曜石read_note：按路径阅读黑曜石金库的一张便条
黑曜石_更新_注释：更新现有注释（替换或附加内容，更新frontmatter）
黑曜石_delete_note：从黑曜石保险库中删除注释
黑曜石_搜索_备注：按内容、文件夹或标签搜索笔记
黑曜石_列表_注释：列出vault或特定文件夹中的所有笔记
黑曜石_get-daily_note：获取或创建特定日期的每日笔记
黑曜石_get_fault_status：获取黑曜石金库的统计数据（总笔记、大小、文件夹分布）

谷歌日历工具（10个工具）

谷歌日历列表日历：列出所有可用的Google日历，包括ID、名称和访问角色
google_calendar_create_event：创建包含标题、时间、描述、位置和与会者的新日历事件
谷歌日历事件：获取指定时间范围内的事件
谷歌日历更新事件：更新现有日历事件（标题、时间、描述、位置）
google_calendar_delete_event：删除日历事件
google_calendar_find_free_slots：在日历中查找可用的时间段以进行日程安排
谷歌日历快速添加：使用自然语言创建活动（例如，“明天中午12点与约翰共进午餐”）
谷歌日历事件：获取今天的所有活动
谷歌日历事件：获取未来N天的活动
谷歌_日历_区块_研究_时间：为学习工作流程创建学习模块活动（与Anki/Obsidian集成）

谷歌日历设置

Google日历集成需要OAuth2身份验证。按照以下步骤进行设置：

第一步：创建谷歌云项目

首选谷歌云控制台
点击顶部的“选择项目”，然后点击“新建项目”
输入项目名称（例如“Bird MCP日历”）
点击“创建”

第2步：启用Google日历API

在您的Google Cloud项目中，转到“API和服务”>“库”
搜索“Google日历API”
点击“谷歌日历API”
点击“启用”

步骤3：配置OAuth同意屏幕

转到“API和服务”>“OAuth同意屏幕”
选择“外部”用户类型（除非您有谷歌工作区）
点击“创建”
填写必填字段：

- 应用程序名称：“鸟MCP服务器” - 用户支持电子邮件：您的电子邮件 - 开发人员联系信息：您的电子邮件

点击“保存并继续”
在“范围”页面上，单击“添加或删除范围”
添加Google日历API范围：

- “Google日历API过滤器” - 选择 https://www.googleapis.com/auth/calendar

点击“更新”，然后点击“保存并继续”
在“测试用户”上，添加您的谷歌帐户电子邮件
点击“保存并继续”

步骤4：创建OAuth2凭据

转到“API和服务”>“凭据”
点击“+创建凭据”>“OAuth客户端ID”
选择“桌面应用程序”作为应用程序类型
输入名称（例如“Bird MCP Desktop”）
点击“创建”
点击“下载JSON”下载您的凭据文件
将文件另存为 credentials.json 在安全的地方

步骤5：配置环境变量

更新您的 .env 包含凭据路径的文件：

# Google Calendar Integration
GOOGLE_CALENDAR_CREDENTIALS_PATH=/absolute/path/to/credentials.json

# Optional: Custom token storage location
# GOOGLE_CALENDAR_TOKEN_PATH=/path/to/token.pickle

重要提示： 使用绝对路径，而不是相对路径，如 ~/ 或 ./

步骤6：初始身份验证

首次使用谷歌日历集成时，您需要进行身份验证：

启动MCP服务器：

   python -m bird_mcp.server

浏览器窗口将自动打开，要求您登录谷歌

使用您作为测试用户添加的Google帐户登录

授予请求的权限（日历访问）

您将在浏览器中看到成功消息

身份验证令牌将自动保存到 ~/.bird_mcp/google_calendar_token.pickle

未来的请求将使用此保存的令牌（无需浏览器）

许可证管理

令牌位置：默认情况下，令牌保存到 ~/.bird_mcp/google_calendar_token.pickle
令牌刷新：令牌过期时会自动刷新
撤销访问权限：要撤销访问权限，请删除令牌文件并从您的应用程序中删除该应用程序 Google帐户权限

谷歌日历故障排除

“找不到凭据文件”

验证 GOOGLE_CALENDAR_CREDENTIALS_PATH 指向正确的文件
使用绝对路径： /Users/username/credentials.json 不 ~/credentials.json

“访问被阻止：此应用程序的请求无效”

确保您在OAuth同意屏幕中将您的电子邮件添加为测试用户
验证您的项目中是否启用了Google日历API

“授予无效”或“令牌已过期或吊销”

删除令牌文件： rm ~/.bird_mcp/google_calendar_token.pickle
重新启动服务器以重新进行身份验证

身份验证期间浏览器未打开

检查终端输出中的身份验证URL
手动将URL复制并粘贴到浏览器中
按照浏览器中的身份验证步骤进行操作

安全考虑

凭据文件：保持 credentials.json 安全-它包含您的OAuth2客户端密钥
令牌文件：令牌文件包含对日历的访问权限-请确保其安全
范围：集成只要求日历访问，不要求其他谷歌服务
测试用户：在开发中，只有作为测试用户添加的帐户才能进行身份验证
出版：要允许任何谷歌帐户，您需要验证您的应用程序（个人使用不需要）

使用Docker

使用Docker时，您需要挂载凭据和令牌文件：

# Create directory for credentials
mkdir -p ~/.bird_mcp

# Copy credentials file
cp /path/to/credentials.json ~/.bird_mcp/

# Run with Docker, mounting the credentials directory
docker run -i --rm \
  --env-file .env \
  -v ~/.bird_mcp:/root/.bird_mcp:rw \
  -e GOOGLE_CALENDAR_CREDENTIALS_PATH=/root/.bird_mcp/credentials.json \
  -e GOOGLE_CALENDAR_TOKEN_PATH=/root/.bird_mcp/google_calendar_token.pickle \
  bird-mcp

备注：第一次使用Docker运行时，OAuth流可能不会自动工作。您需要：

首先在您的主机上运行身份验证（在Docker之外）
然后使用Docker保存令牌文件

故障排除

服务器无法启动

症状： 服务器无法启动或立即崩溃

解决：

检查环境变量

   # Ensure .env file exists
   ls -la .env

   # Check TODOIST_API_TOKEN is set
   cat .env | grep TODOIST_API_TOKEN

检查Python版本

   # Requires Python 3.10+
   python --version

检查相关性

   # With uv
   uv sync

   # With pip
   pip install -r requirements.txt

检查日志

   # Run server directly to see errors
   python -m bird_mcp.server

   # Look for error messages in output

验证软件包安装

   # Check if package is installed
   pip list | grep bird-mcp

   # Reinstall if missing
   pip install -e .

Claude代码问题

症状： Claude Code找不到或无法连接到MCP服务器

解决：

验证服务器是否已配置

   # List configured servers
   claude mcp list

   # Should show: bird-personal-assistant: python -m bird_mcp.server - ✓ Connected

   # The server needs to find .env file
   pwd  # Should show /path/to/bird
   ls .env  # Should exist

手动测试服务器

   # Run server to check for errors
   python -m bird_mcp.server

   # Should see initialization logs:
   # INFO - Initializing Todoist integration...
   # INFO - Todoist integration initialized successfully

重新添加服务器

   # Remove and re-add
   claude mcp remove bird-personal-assistant
   claude mcp add --transport stdio --scope local bird-personal-assistant -- python -m bird_mcp.server

检查环境变量是否可访问

   # Print environment variable (should show your token)
   echo $TODOIST_API_TOKEN

   # If empty, source .env
   export $(cat .env | xargs)

Claude桌面/光标连接问题

症状： Claude Desktop显示服务器已断开连接或工具未显示

解决：

验证MCP配置文件位置

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

检查JSON语法

   # Validate JSON syntax
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool

验证Python路径

   # Check which Python is being used
   which python

   # Use absolute path in config if needed
   /full/path/to/python -m bird_mcp.server

检查配置中的环境变量

- 确保 TODOIST_API_TOKEN 设置在 env 章节 - 使用绝对路径 OBSIDIAN_VAULT_PATH

重新启动克劳德桌面

- 完全退出Claude Desktop（不仅仅是关闭窗口） - 重新打开并检查服务器状态

MCP客户端无法连接

验证服务器是否正在运行：测试 python -m bird_mcp.server 直接
检查MCP配置：确保MCP设置中的命令和参数正确
检查环境变量：确保它们设置在MCP配置中，或 .env 文件
检查Python路径：确保安装了软件包(pip install -e . 或 uv pip install -e .)

Docker问题

症状： Docker容器无法启动或崩溃

解决：

端口冲突 （仅开发模式）

   # Check if ports are in use
   lsof -i :6274
   lsof -i :6277

   # Kill process using port if needed
   kill -9

环境变量

   # Ensure .env file exists
   ls -la .env

   # Check format (no quotes around values)
   cat .env

构建缓存问题

   # Rebuild without cache
   docker-compose build --no-cache

   # Or with docker directly
   docker build --no-cache -t bird-mcp .

卷装载问题 （黑曜石）

   # Check vault path exists
   ls -la /path/to/obsidian/vault

   # Ensure path is absolute in docker-compose.yml
   # Correct: /Users/username/obsidian_vault:/app/vault:rw
   # Wrong: ~/obsidian_vault:/app/vault:rw

查看容器日志

   # With docker-compose
   docker-compose logs -f bird-mcp

   # With docker
   docker logs bird-mcp

Todoist API问题

症状： Todoist工具返回错误或失败

解决：

验证API令牌

   # Get new token from https://todoist.com/app/settings/integrations/developer
   # Update .env file with new token

检查API费率限制

- Todoist有费率限制（因计划而异） - 请稍候几分钟，然后重试

手动测试令牌

   # Test with curl
   curl https://api.todoist.com/rest/v2/projects \
     -H "Authorization: Bearer YOUR_TOKEN_HERE"

AnkiConnect问题

症状： Anki工具失败或返回连接错误

解决：

验证AnkiConnect是否已安装

   # Open Anki → Tools → Add-ons
   # Should see "AnkiConnect" in the list
   # Code: 2055492159

检查Anki是否正在运行

   # Anki must be open for AnkiConnect to work
   # Start Anki application

验证端口

   # Test connection
   curl http://localhost:8765

   # Should return AnkiConnect API info

检查防火墙

- 一些防火墙阻止本地主机连接 - 允许连接到端口8765

使用Docker进行测试

   # Use host.docker.internal instead of localhost
   # Already configured in docker-compose.yml

使用健康检查

   # Run health check to test all services
   # In Claude Code:
   "Check the health of my MCP server"

黑曜石整合问题

症状： 黑曜石工具返回“找不到保险库”错误

解决：

验证vault路径

   # Check path exists
   ls -la /path/to/obsidian/vault

   # Update .env
   OBSIDIAN_VAULT_PATH=/absolute/path/to/vault

检查路径是否为绝对路径

   # Correct: /Users/username/obsidian_vault
   # Wrong: ~/obsidian_vault
   # Wrong: ../obsidian_vault

验证权限

   # Check read/write permissions
   ls -ld /path/to/obsidian/vault

   # Should show drwxr-xr-x or similar

Docker保险库安装

- 确保卷已装载到docker-compose.yml中 - 对主机目录使用绝对路径 - 集 OBSIDIAN_VAULT_PATH=/app/vault 集装箱内部

常见错误消息

“ModuleNotFoundation错误：没有名为'bird_mcp'的模块”

解决方案：使用安装包 pip install -e . 或 uv pip install -e .

“Todoist集成已禁用”

解决方案：设置 TODOIST_API_TOKEN 在 .env 文件

“AnkiConnect错误：连接被拒绝”

解决方案：启动Anki应用程序

“保险库路径不存在”

解决方案：检查 OBSIDIAN_VAULT_PATH 是正确的绝对路径

“'list'对象没有属性'id'”

这是早期版本中的一个错误，请确保您使用的是最新代码

获取帮助

如果您仍然遇到问题：

检查日志

   # Run with verbose output
   python -m bird_mcp.server 2>&1 | tee server.log

健康检查测试

   # In Claude Code, ask:
   "Run a health check on the MCP server"

报告问题

- GitHub问题：创建问题 - 包括日志、错误消息和您的设置（操作系统、Python版本等）

许可证

麻省理工学院

bird (Tamdogood)

快速接入

详细介绍

Bird MCP服务器

目录

快速参考

特性

目前已实施

先决条件

快速开始

1.获取您的API代币

2.设置环境变量

安装与运行

选项1：使用紫外线（推荐）

安装uv

安装依赖项

运行服务器

选项2：使用pip

创建虚拟环境

安装依赖项

运行服务器

选项3：使用Docker

使用Docker Compose构建和运行

安装黑曜石保险库（黑曜岩集成所需）

直接使用Docker构建和运行

在Claude Desktop中使用Docker

包装

封装结构

构建包

方法1：使用紫外线（推荐）

方法2：使用pip和setuptools

从源安装

从本地目录安装

从Git仓库安装

从内置车轮安装

发布到PyPI（未来）

验证安装

依赖管理

更新依赖关系

同步依赖关系

MCP客户端配置

Claude桌面/光标配置

Claude代码配置

快速设置

验证连接

Claude代码的环境变量

测试集成

删除服务器

发展

项目架构

项目结构

开发设置

添加新的MCP工具

1.创建或更新工具实现

2.在server.py中初始化工具

3.在MCP注册工具

4.添加健康检查（可选）

5.更新依赖关系（如果需要）

6.更新环境变量

7.测试你的工具

8.更新文档

运行测试

代码格式化

使用MCP Inspector进行开发

可用工具

健康检查（1个工具）

Todoist工具（11个工具）

Anki工具（14个工具）

黑曜石工具（8工具）

谷歌日历工具（10个工具）

谷歌日历设置

第一步：创建谷歌云项目

第2步：启用Google日历API

步骤3：配置OAuth同意屏幕

步骤4：创建OAuth2凭据

步骤5：配置环境变量

步骤6：初始身份验证

许可证管理

谷歌日历故障排除

安全考虑