Pinboard MCP 服务器

通过模型上下文协议 (MCP) 为 LLM 提供对 Pinboard.in 书签的只读访问权限。

概述

该服务器使 LLM 能够在推理时搜索、过滤和检索来自 Pinboard.in 的书签元数据。它基于 FastMCP 2.0 构建，提供了四个用于书签交互的核心工具，同时遵守 Pinboard 的速率限制并实现了智能缓存。

Related MCP server: Raindrop.io MCP Server

功能

• 只读访问：访问 Pinboard 书签

• 五个 MCP 工具：search_bookmarks、search_bookmarks_extended、list_recent_bookmarks、list_bookmarks_by_tags、list_tags

• 智能缓存：使用 LRU 缓存，并通过 posts/update 端点实现自动失效

• 速率限制：遵守 Pinboard 在 API 调用之间 3 秒的准则

• 字段映射：将 Pinboard 的旧字段名称转换为直观名称（description→title，extended→notes）

• 全面测试：包含集成测试工具和 CI 验证

安装

通过 pip 安装（推荐）

pip install pinboard-bookmarks-mcp-server

从源码安装

git clone https://github.com/rossshannon/pinboard-bookmarks-mcp-server.git
cd pinboard-bookmarks-mcp-server
pip install -e .

快速入门

1. 获取您的 Pinboard API 令牌：访问 https://pinboard.in/settings/password

2. 设置环境变量：

   export PINBOARD_TOKEN="username:1234567890ABCDEF"

3. 启动服务器：

   pinboard-mcp-server

4. 验证是否正常工作：

   # Test help command (works without token)
   pinboard-mcp-server --help
   
   # Server should show "Starting MCP server" when run with token

在 Claude Desktop 中使用

将此配置添加到您的 Claude Desktop 设置中：

{
  "mcpServers": {
    "pinboard": {
      "command": "pinboard-mcp-server",
      "env": {
        "PINBOARD_TOKEN": "your-username:your-token-here"
      }
    }
  }
}

可用工具

1. search_bookmarks

通过查询字符串搜索标题、备注和标签中的书签。侧重于近期内容，并具有自动扩展功能。

参数：

• query (string): 搜索查询

• limit (int, optional): 最大结果数（默认：20，最大：100）

示例：

Search for "python testing" bookmarks

2. search_bookmarks_extended

扩展搜索，用于获取标题、备注和标签中全面的历史结果。

参数：

• query (string): 搜索查询

• days_back (int, optional): 向前回溯搜索的天数（默认：365，最大：730）

• limit (int, optional): 最大结果数（默认：100，最大：200）

示例：

Search the last 2 years for "kubernetes" bookmarks

3. list_recent_bookmarks

列出过去 N 天内保存的书签。

参数：

• days (int, optional): 向前回溯的天数（默认：7，最大：30）

• limit (int, optional): 最大结果数（默认：20，最大：100）

示例：

Show me bookmarks from the last 3 days

4. list_bookmarks_by_tags

按标签过滤并列出所有书签，支持可选的日期范围。对于历史访问最有效。

参数：

• tags (array): 要过滤的标签列表（1-3 个标签）

• from_date (string, optional): ISO 格式的开始日期 (YYYY-MM-DD)

• to_date (string, optional): ISO 格式的结束日期 (YYYY-MM-DD)

• limit (int, optional): 最大结果数（默认：100，最大：200）

示例：

Find bookmarks tagged with "python" and "api" from January 2024

5. list_tags

列出所有标签及其使用次数。

示例：

What are my most used tags?

配置

环境变量

• PINBOARD_TOKEN (required): 您的 Pinboard API 令牌，格式为 username:token

速率限制

服务器会自动在 Pinboard API 调用之间强制执行 3 秒的延迟，以遵守其准则。缓存的响应会立即返回。

缓存策略

• 查询缓存：包含 1000 个条目的 LRU 缓存，用于搜索结果

• 书签缓存：完整的书签列表缓存 1 小时

• 缓存失效：使用 posts/update 端点检测更改

• 标签缓存：标签列表缓存直到手动刷新

测试

该项目包含多种测试策略的全面测试覆盖：

运行所有测试

# Activate virtual environment first
source ~/.venvs/pinboard-bookmarks-mcp-server/bin/activate

# Run all tests with coverage
pytest --cov=src --cov-report=term-missing

真实 API 测试

# Set your Pinboard token
export PINBOARD_TOKEN="username:token"

# Run debug utility to test search functionality (development only)
PINBOARD_TOKEN="username:token" python tests/debug_bookmarks.py

模拟 API 测试

# Run comprehensive test suite (development only)
python -m pytest tests/ -v

开发

设置

# Clone and setup
git clone https://github.com/rossshannon/pinboard-bookmarks-mcp-server.git
cd pinboard-bookmarks-mcp-server

# Quick development setup
./scripts/dev-setup.sh

代码质量

# Activate environment
source ~/.venvs/pinboard-bookmarks-mcp-server/bin/activate

# Linting and formatting
ruff check src/ tests/
ruff format src/ tests/

# Type checking
mypy src/

# Run tests
pytest -v

# Build package
./scripts/build.sh

架构

• FastMCP 2.0: 带有工具抽象和异步 FastAPI 服务器的 MCP 脚手架

• pinboard.py: 带有错误处理的 Pinboard API 客户端包装器

• Pydantic: 使用 JSON Schema 进行数据验证和序列化

• ThreadPoolExecutor: 连接异步 MCP 与同步 pinboard.py 库

• LRU Cache: 带有智能失效机制的内存缓存

关键文件

• src/pinboard_mcp_server/main.py - MCP 服务器入口点和工具实现

• src/pinboard_mcp_server/client.py - 带有缓存功能的 Pinboard API 客户端

• src/pinboard_mcp_server/models.py - Pydantic 数据模型

• tests/ - 全面的测试套件

• tests/debug_bookmarks.py - 用于测试搜索功能的调试工具

• docs/TEST_HARNESS.md - 测试工具文档

性能

• P50 响应时间: <250ms (缓存响应)

• P95 响应时间: <600ms (冷缓存)

• 速率限制: API 调用之间 3 秒间隔

• 缓存命中率: 典型使用模式下 >90%

安全性

• API 令牌绝不会被记录或在错误消息中暴露

• 对 Pinboard 数据进行只读访问

• 对所有工具参数进行输入验证

• 安全的环境变量处理

故障排除

常见问题

"PINBOARD_TOKEN environment variable is required"

• 确保已设置令牌：export PINBOARD_TOKEN="username:token"

• 从 https://pinboard.in/settings/password 获取您的令牌

• 令牌格式应为：username:1234567890ABCDEF

"Command not found: pinboard-mcp-server"

• 确保已安装该包：pip install pinboard-bookmarks-mcp-server

• 检查您的 Python 环境是否已激活

• 尝试重新安装：pip uninstall pinboard-bookmarks-mcp-server && pip install pinboard-bookmarks-mcp-server

服务器启动但 Claude Desktop 无法连接

• 验证 Claude Desktop 设置中的 MCP 配置

• 检查 command 路径是否正确：pinboard-mcp-server

• 确保在 env 部分设置了 PINBOARD_TOKEN

"Permission denied" 或 "Access denied" 错误

• 验证您的 Pinboard 令牌是否有效且处于活动状态

• 检查您是否有互联网连接以访问 pinboard.in

• 在 https://pinboard.in/api/v1/posts/recent 手动测试您的令牌

贡献

1. Fork 本仓库

2. 创建功能分支 (git checkout -b feature/amazing-feature)

3. 进行更改并添加测试

4. 确保所有测试通过且代码格式正确

5. 提交 Pull Request

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。