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 북마크에 대한 읽기 전용 액세스를 제공합니다.

개요

이 서버는 LLM이 추론 시점에 Pinboard.in에서 북마크 메타데이터를 검색, 필터링 및 가져올 수 있는 기능을 제공합니다. 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

  • posts/update 엔드포인트를 사용한 LRU 캐시 및 자동 무효화 기능을 갖춘 스마트 캐싱

  • API 호출 간 Pinboard의 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. 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, 선택 사항): 최대 결과 수 (기본값: 20, 최대: 100)

예시:

Search for "python testing" bookmarks

2. search_bookmarks_extended

제목, 메모 및 태그 전체에서 포괄적인 과거 결과를 검색하기 위한 확장 검색입니다.

매개변수:

  • query (string): 검색 쿼리

  • days_back (int, 선택 사항): 검색할 과거 일수 (기본값: 365, 최대: 730)

  • limit (int, 선택 사항): 최대 결과 수 (기본값: 100, 최대: 200)

예시:

Search the last 2 years for "kubernetes" bookmarks

3. list_recent_bookmarks

최근 N일 동안 저장된 북마크를 나열합니다.

매개변수:

  • days (int, 선택 사항): 과거 조회 일수 (기본값: 7, 최대: 30)

  • limit (int, 선택 사항): 최대 결과 수 (기본값: 20, 최대: 100)

예시:

Show me bookmarks from the last 3 days

4. list_bookmarks_by_tags

선택적 날짜 범위를 사용하여 태그별로 필터링된 모든 북마크를 나열합니다. 과거 데이터 액세스에 가장 효율적입니다.

매개변수:

  • tags (array): 필터링할 태그 목록 (1-3개 태그)

  • from_date (string, 선택 사항): ISO 형식의 시작 날짜 (YYYY-MM-DD)

  • to_date (string, 선택 사항): ISO 형식의 종료 날짜 (YYYY-MM-DD)

  • limit (int, 선택 사항): 최대 결과 수 (기본값: 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의 가이드라인을 준수하기 위해 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

모의(Mock) 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 스키마를 사용한 데이터 검증 및 직렬화

  • 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 환경 변수가 필요합니다"

  • 토큰을 설정했는지 확인하세요: export PINBOARD_TOKEN="username:token"

  • https://pinboard.in/settings/password 에서 토큰을 가져오세요

  • 토큰 형식은 username:1234567890ABCDEF여야 합니다

"명령어를 찾을 수 없음: 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