Pinboard MCP Server
Pinboard MCP サーバー
Model Context Protocol (MCP) を介して、LLM に Pinboard.in のブックマークへの読み取り専用アクセスを提供します。
概要
このサーバーは、推論時に Pinboard.in からブックマークのメタデータを検索、フィルタリング、取得する機能を LLM に提供します。FastMCP 2.0 上に構築されており、Pinboard のレート制限を遵守し、インテリジェントなキャッシュを実装しながら、ブックマーク操作のための 4 つのコアツールを提供します。
Related MCP server: Raindrop.io MCP Server
特徴
Pinboard ブックマークへの読み取り専用アクセス
5 つの MCP ツール:
search_bookmarks,search_bookmarks_extended,list_recent_bookmarks,list_bookmarks_by_tags,list_tagsLRU キャッシュと
posts/updateエンドポイントを使用した自動無効化によるスマートキャッシュAPI 呼び出し間の 3 秒間隔という Pinboard のガイドラインを遵守するレート制限
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 .クイックスタート
https://pinboard.in/settings/password から Pinboard API トークンを取得します。
環境変数を設定します:
export PINBOARD_TOKEN="username:1234567890ABCDEF"サーバーを起動します:
pinboard-mcp-server動作を確認します:
# 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" bookmarks2. search_bookmarks_extended
タイトル、ノート、タグ全体を対象とした、包括的な履歴結果のための拡張検索です。
パラメータ:
query(string): 検索クエリdays_back(int, optional): 検索対象とする過去の日数 (デフォルト: 365, 最大: 730)limit(int, optional): 最大結果数 (デフォルト: 100, 最大: 200)
例:
Search the last 2 years for "kubernetes" bookmarks3. list_recent_bookmarks
過去 N 日間に保存されたブックマークを一覧表示します。
パラメータ:
days(int, optional): 遡る日数 (デフォルト: 7, 最大: 30)limit(int, optional): 最大結果数 (デフォルト: 20, 最大: 100)
例:
Show me bookmarks from the last 3 days4. 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 20245. list_tags
すべてのタグとその使用回数を一覧表示します。
例:
What are my most used tags?設定
環境変数
PINBOARD_TOKEN(必須):username:token形式の Pinboard API トークン
レート制限
サーバーは、Pinboard のガイドラインを遵守するため、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-serverPython 環境がアクティブであることを確認してください
再インストールを試してください:
pip uninstall pinboard-bookmarks-mcp-server && pip install pinboard-bookmarks-mcp-server
サーバーは起動するが Claude Desktop が接続できない
Claude Desktop 設定の MCP 構成を確認してください
commandパスが正しいことを確認してください:pinboard-mcp-serverenvセクションでPINBOARD_TOKENが設定されていることを確認してください
"Permission denied" または "Access denied" エラー
Pinboard トークンが有効でアクティブであることを確認してください
pinboard.in に到達するためのインターネット接続があることを確認してください
https://pinboard.in/api/v1/posts/recent でトークンを手動でテストしてください
貢献
リポジトリをフォークします
フィーチャーブランチを作成します (
git checkout -b feature/amazing-feature)テストを伴う変更を行います
すべてのテストがパスし、コードがフォーマットされていることを確認します
プルリクエストを送信します
ライセンス
MIT ライセンス - 詳細は LICENSE ファイルを参照してください。
Available Tools
5 toolslist_bookmarks_by_tagsA
List ALL bookmarks filtered by tags and optional date range.
Args:
tags: List of tags to filter by (1-3 tags)
from_date: Start date in ISO format (YYYY-MM-DD), optional
to_date: End date in ISO format (YYYY-MM-DD), optional
limit: Maximum number of results to return (1-200, default 100)
Note: Gets ALL bookmarks with specified tags, regardless of age.
Very efficient for tag-based searches. Provides generous data for analysis.
Inputs: tags (required), from_date, to_date, limit.
list_recent_bookmarksA
List bookmarks saved in the last N days.
Args:
days: Number of days to look back (1-30, default 7)
limit: Maximum number of results to return (1-100, default 20)
Inputs: days, limit.
list_tagsA
List all tags with their usage counts.
Inputs: no named parameters.
search_bookmarksA
Search bookmarks by query string across titles, notes, and tags (recent focus).
Args:
query: Search query to match against bookmark titles, notes, and tags
limit: Maximum number of results to return (1-100, default 20)
Note: Searches recent bookmarks first, expands automatically if needed.
For comprehensive historical search, use search_bookmarks_extended.
Inputs: query (required), limit.
search_bookmarks_extendedA
Extended search for comprehensive historical results across titles, notes, and tags.
Args:
query: Search query to match against bookmark titles, notes, and tags
days_back: How many days back to search (1-730, default 365 = 1 year)
limit: Maximum number of results to return (1-200, default 100)
Note: Provides comprehensive results while being mindful of server load.
Use tag-based searches for most efficient access to historical bookmarks.
Inputs: query (required), days_back, limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct purpose: listing by tags, recent bookmarks, tag counts, and two search variants differentiated by scope (recent vs. historical). Minimal overlap.
All tools follow a consistent verb_noun pattern: 'list_' for listing and 'search_' for searching, with descriptive suffixes. No style mixing.
5 tools for a bookmark server is a reasonable count, though the set lacks write operations like add/delete. Still well-scoped for a query-focused service.
The tool set covers only read and search operations. Missing essential CRUD actions (create, update, delete bookmarks), which are typical for bookmark management.
Maintenance
Related MCP Connectors
Search and chat with your X bookmarks, with citations back to the original posts.
Save, search, read, tag, and organize your bookmarks from AI assistants with OAuth sign-in.
All your bookmarks in one library. Share them with your AI agents. Read-only search over your saves.
Your portable context layer — load it into any AI.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables users to access and manage their Pinboard bookmarks directly through Claude Desktop. Supports retrieving, adding, and updating bookmarks with date filtering, tagging, and bookmark analysis capabilities.10-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to access and manage Raindrop.io bookmarks, collections, tags, and highlights through the Model Context Protocol. Supports CRUD operations, advanced search, file uploads, and bulk editing of bookmarks.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to save and search bookmarks using OpenAI's RAG capabilities for intelligent bookmark management and retrieval.MIT
- AlicenseNot gradedqualityDmaintenanceEnables language models to access and manage Raindrop.io bookmarks, collections, tags, and highlights through the Model Context Protocol.86 npmMIT