Skip to main content
Glama
Pinboard MCP Server

Pinboard MCP Server

by rossshannon

Pinboard MCP サーバー

CI Python 3.10+

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_tags

  • LRU キャッシュと 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 .

クイックスタート

  1. https://pinboard.in/settings/password から Pinboard API トークンを取得します。

  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 (必須): 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-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. リポジトリをフォークします

  2. フィーチャーブランチを作成します (git checkout -b feature/amazing-feature)

  3. テストを伴う変更を行います

  4. すべてのテストがパスし、コードがフォーマットされていることを確認します

  5. プルリクエストを送信します

ライセンス

MIT ライセンス - 詳細は LICENSE ファイルを参照してください。

Available Tools

5 tools
list_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

    A4.1/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern: 'list_' for listing and 'search_' for searching, with descriptive suffixes. No style mixing.

    Tool Count4/5

    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.

    Completeness2/5

    The tool set covers only read and search operations. Missing essential CRUD actions (create, update, delete bookmarks), which are typical for bookmark management.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to save and search bookmarks using OpenAI's RAG capabilities for intelligent bookmark management and retrieval.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables language models to access and manage Raindrop.io bookmarks, collections, tags, and highlights through the Model Context Protocol.
      86 npm
      MIT