Bookmarks MCP Server

Postgres 기반 북마크 관리자이자 범용 REST API 도구로, MCP 서버로 노출되어 LLM 클라이언트(예: Claude Desktop)가 사용자를 대신해 북마크를 저장, 검색, 관리할 수 있게 합니다.

기능

• asyncpg를 통해 Postgres에 북마크(url, title, description, tags)를 저장합니다

• CRUD 도구를 노출합니다: add_bookmark, list_bookmarks, get_bookmark, search_bookmarks, update_bookmark, delete_bookmark

• DB 검사 도구를 노출합니다: list_tables, describe_table, run_query(안전을 위해 SELECT 전용)

• 범용 REST 도구 하나인 api_request를 노출합니다. .env의 API_BASE_URL로 구성한 모든 API를 호출합니다(모든 메서드, 경로, 쿼리 매개변수, JSON 본문). 기본적으로는 Microlink(무료, API 키 불필요)를 사용해 URL을 저장하기 전에 링크 미리보기(title/description/image)를 가져오도록 설정되어 있습니다.

Related MCP server: veyra-bookmarks

설정

1. 데이터베이스

전용 role과 데이터베이스를 생성합니다(앱 자체에 Postgres 슈퍼유저를 사용하지 마세요):

CREATE ROLE bookmarks_app WITH LOGIN PASSWORD 'choose-a-password';
CREATE DATABASE bookmarks OWNER bookmarks_app;

그런 다음 테이블을 생성합니다:

psql -U bookmarks_app -h localhost -d bookmarks -f schema.sql

2. Python 환경

python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS/Linux
pip install -r requirements.txt

3. .env 구성

copy .env.example .env        # Windows
# cp .env.example .env        # macOS/Linux

다음을 입력합니다:

• DATABASE_URL — bookmarks_app 연결 문자열

• API_BASE_URL / API_KEY — api_request가 호출할 REST API(기본값은 키가 필요 없는 Microlink입니다. 인증이 필요 없는 API는 API_KEY를 비워 두세요)

4. 실행

python src/server.py

Claude Desktop에 연결

claude_desktop_config.json에 항목을 추가합니다:

{
  "mcpServers": {
    "bookmarks": {
      "command": "/absolute/path/to/bookmarks-server/venv/Scripts/python.exe",
      "args": ["/absolute/path/to/bookmarks-server/src/server.py"]
    }
  }
}

환경 변수는 .env에서 읽습니다(python-dotenv를 통해, 프로세스의 작업 디렉터리와 관계없이 프로젝트 루트 기준으로 해석됩니다). 따라서 민감한 정보는 Claude 구성 자체에 넣을 필요가 없습니다.

Windows Store(MSIX) 설치판 Claude Desktop: 구성 파일은 일반적인 %APPDATA%\Claude\ 경로에 있지 않습니다. %LOCALAPPDATA%\Packages\<Claude package id>\LocalCache\Roaming\Claude\claude_desktop_config.json 아래 샌드박스에 있습니다. 편집하기 전에 시스템 트레이에서 Claude Desktop을 완전히 종료하고(창을 닫는 것만으로는 안 됩니다) 다시 실행하세요.

보안 참고 사항

• 모든 쿼리는 매개변수화된 SQL($1, $2, ...)을 사용합니다. 문자열로 SQL을 만들지 않으므로 도구 인자로 인한 주입 위험이 없습니다.

• run_query는 SELECT 문만 허용합니다. 쓰기는 전용 CRUD 도구를 통해서만 수행되며, 이는 LLM 기반 클라이언트를 위해 의도적으로 공격 표면을 좁힌 것입니다.

• bookmarks_app은 bookmarks 데이터베이스로 범위가 제한된 슈퍼유저가 아닌 role입니다. 서버는 Postgres 슈퍼유저로 연결하지 않습니다.

• .env는 gitignore 처리되어 있습니다. 실제 자격 증명을 커밋하지 마세요. 템플릿으로 .env.example을 사용하세요.