Simplenote MCP 服务器

一个 FastMCP/FastAPI 服务器，使 Claude Desktop 能够通过模型上下文协议 (MCP) 与 Simplenote 笔记进行交互。

功能特性

• 通过 MCP 列出、查看、创建、更新和删除 Simplenote 笔记
• 按内容搜索笔记
• 按标签过滤笔记
• 具有后台同步功能的内存缓存
• Bearer token 身份验证
• 为 Claude Desktop 提供 CORS 支持

要求

• Python 3.11+
• macOS 15+（主要平台，但也应该可以在其他平台上工作）
• Simplenote 帐户
• uv 包管理器（用于安装依赖项）

安装说明

1. 克隆存储库

git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server

2. 创建配置文件

在根目录中创建一个 .env 文件，其中包含以下变量：

SIMPLENOTE_EMAIL=your.email@example.com
SIMPLENOTE_PASSWORD=your_password
SERVER_PORT=8000
SERVER_AUTH_TOKEN=your_secure_token
SYNC_INTERVAL_SECONDS=120

# 速率限制和超时设置
DEFAULT_RATE_LIMIT="50/minute"
API_RATE_LIMIT="100/minute"
HEALTH_RATE_LIMIT="10/minute"
REQUEST_TIMEOUT_SECONDS=30

# 安全设置 - 允许的主机名列表，以逗号分隔（默认禁用）
# TRUSTED_HOSTS=localhost,127.0.0.1

注意：

• 如果未指定，SERVER_PORT 默认为 8000
• SYNC_INTERVAL_SECONDS 控制服务器与 Simplenote 同步的频率（默认为 60 秒）
• 选择一个强且唯一的 SERVER_AUTH_TOKEN，因为它将用于验证 Claude Desktop
• 速率限制设置控制每个时间段的最大请求数：
  • API_RATE_LIMIT: 应用于所有 API 端点 (默认: 100/分钟)
  • HEALTH_RATE_LIMIT: 应用于健康检查端点 (默认: 10/分钟)
  • DEFAULT_RATE_LIMIT: 默认回退速率限制 (默认: 50/分钟)
• REQUEST_TIMEOUT_SECONDS: 请求在超时之前可以花费的最长时间（以秒为单位）（默认值：30）
• TRUSTED_HOSTS: 可选的以逗号分隔的允许主机名列表，用于增强安全性

3. 安装 uv 包管理器

如果您尚未安装 uv：

# 使用 pip
pip install uv

# 或者在 macOS 上使用 homebrew
brew install uv

4. 运行服务器

包含的脚本处理创建虚拟环境、安装依赖项和启动服务器：

chmod +x run_server.sh
./run_server.sh

服务器将在配置的端口上启动（默认：8000）。

手动设置（替代方法）

如果您更喜欢手动设置环境：

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate

# 安装依赖项
pip install -r requirements.txt

# 启动服务器
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

配置 Claude Desktop

要配置 Claude Desktop 以使用此 MCP 服务器：

1. 在 Claude Desktop 中，转到 Settings > Model Context Protocol
2. 添加一个新的 MCP 服务器，其中包含以下详细信息：
   • URL: http://localhost:8000（或您配置的端口）
   • Authentication: Bearer token
   • Token: 您为 SERVER_AUTH_TOKEN 设置的值
3. 保存配置并启用 MCP 服务器

API 端点

健康检查

• GET /health: 检查服务器是否正在运行

MCP 发现

• GET /api/v1/discovery: 列出所有可用的工具及其模式（由 Claude Desktop 使用）

工具

所有工具端点都使用 POST /api/v1/tools/{tool_name} 和 JSON 请求体

列出笔记

• Endpoint: POST /api/v1/tools/list_notes
• Request: {} 或 {"tag": "tag-name"} 按标签过滤
• Response: 笔记对象数组

获取笔记

• Endpoint: POST /api/v1/tools/get_note
• Request: {"note_id": "string"}
• Response: 笔记对象

创建笔记

• Endpoint: POST /api/v1/tools/create_note
• Request: {"content": "string", "tags": ["string"]}
• Response: 创建的笔记对象

更新笔记

• Endpoint: POST /api/v1/tools/update_note
• Request: {"note_id": "string", "content": "string", "tags": ["string"]}
• Response: 更新的笔记对象

删除笔记

• Endpoint: POST /api/v1/tools/trash_note
• Request: {"note_id": "string"}
• Response: 指示成功的布尔值

搜索笔记

• Endpoint: POST /api/v1/tools/search_notes
• Request: {"query": "string"}
• Response: 匹配的笔记对象数组

笔记对象模式

{
  "key": "string",
  "content": "string",
  "tags": ["string"],
  "createdate": "2024-01-01T12:00:00Z",
  "modifydate": "2024-01-02T15:30:00Z",
  "deleted": false,
  "systemtags": []
}

运行测试

# 安装测试依赖项
pip install pytest pytest-asyncio pytest-cov

# 运行所有测试
python -m pytest

# 运行带有覆盖率报告的测试
python -m pytest --cov=app

故障排除

连接问题

• 验证服务器是否在预期的端口上运行
• 检查您的防火墙是否允许连接到该端口
• 确保您的 Simplenote 凭据正确

身份验证问题

• 验证您的 .env 文件中的 SERVER_AUTH_TOKEN 是否与 Claude Desktop 中配置的令牌匹配
• 检查服务器日志中是否存在身份验证错误

同步问题

• 如果笔记未出现，请尝试重新启动服务器以强制完全同步
• 检查服务器日志中是否存在任何 API 错误

安全注意事项

• 在生产环境中使用 HTTPS
• 确保您的 SERVER_AUTH_TOKEN 安全
• 仅将敏感凭据存储在 .env 文件中（切勿提交到版本控制）
• 该服务器专为单用户使用而设计，不适用于多租户部署
• 启用速率限制以防止滥用（通过环境变量配置）
• 配置请求超时以防止长时间运行的请求消耗资源
• 在生产环境中，通过设置 TRUSTED_HOSTS 环境变量来启用受信任主机中间件

许可证

MIT