Bookmarks MCP Server

Сервер управления закладками на базе Postgres, а также универсальный инструмент REST API, представленный как сервер MCP, чтобы LLM-клиент (например, Claude Desktop) мог сохранять, искать и управлять закладками от вашего имени.

Что он делает

• Хранит закладки (url, заголовок, описание, теги) в Postgres через asyncpg

• Предоставляет CRUD-инструменты: add_bookmark, list_bookmarks, get_bookmark, search_bookmarks, update_bookmark, delete_bookmark

• Предоставляет инструменты для инспекции БД: list_tables, describe_table, run_query (только SELECT, для безопасности)

• Предоставляет один универсальный REST-инструмент api_request, который вызывает любой API, настроенный через API_BASE_URL в .env (любой метод, путь, параметры запроса, 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 — REST API, который вы хотите вызывать через api_request (по умолчанию Microlink, которому не нужен ключ; оставьте API_KEY пустым для любого API, не требующего аутентификации)

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.

Установки Claude Desktop из Windows Store (MSIX): файл конфигурации находится не по обычному пути %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 в качестве шаблона.