Bookmarks MCP Server

一个基于 Postgres 的书签管理器，外加一个通用 REST API 工具，以 MCP 服务器的形式提供，使 LLM 客户端（例如 Claude Desktop）能够代表你保存、搜索和管理书签。

功能

• 通过 asyncpg 将书签（url、标题、描述、标签）存储在 Postgres 中

• 提供 CRUD 工具：add_bookmark、list_bookmarks、get_bookmark、search_bookmarks、update_bookmark、delete_bookmark

• 提供数据库检查工具：list_tables、describe_table、run_query（仅限 SELECT，出于安全考虑）

• 提供一个通用 REST 工具 api_request，用于调用你通过 .env 中的 API_BASE_URL 配置的任何 API（任意方法、路径、查询参数、JSON 主体）——默认配置为使用 Microlink（免费，无需 API 密钥）在保存 URL 之前获取链接预览（标题/描述/图片）

Related MCP server: veyra-bookmarks

设置

1. 数据库

创建一个专用角色和数据库（不要为应用本身使用 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 应用商店（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 数据库——服务器永远不会以 Postgres 超级用户身份连接。

• .env 已被 gitignore。切勿提交真实凭据——请使用 .env.example 作为模板。