Servidor de marcadores MCP

Un gestor de marcadores respaldado por Postgres, además de una herramienta REST API genérica, expuesto como un servidor MCP para que un cliente LLM (p. ej. Claude Desktop) pueda guardar, buscar y gestionar marcadores en tu nombre.

Qué hace

• Almacena marcadores (url, título, descripción, etiquetas) en Postgres mediante asyncpg

• Expone herramientas CRUD: add_bookmark, list_bookmarks, get_bookmark, search_bookmarks, update_bookmark, delete_bookmark

• Expone herramientas de inspección de BD: list_tables, describe_table, run_query (solo SELECT, por seguridad)

• Expone una herramienta REST genérica, api_request, que llama a cualquier API que configures mediante API_BASE_URL en .env (cualquier método, ruta, parámetros de consulta, cuerpo JSON) — por defecto está configurada para usar Microlink (gratuito, sin clave API) para obtener vistas previas de enlaces (título/descripción/imagen) de una URL antes de guardarla

Related MCP server: veyra-bookmarks

Configuración

1. Base de datos

Crea un rol y una base de datos dedicados (no uses el superusuario de Postgres para la aplicación en sí):

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

Luego crea la tabla:

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

2. Entorno de Python

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

3. Configura .env

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

Completa:

• DATABASE_URL — la cadena de conexión de bookmarks_app

• API_BASE_URL / API_KEY — la REST API que quieres que api_request llame (por defecto es Microlink, que no necesita clave; deja API_KEY en blanco para cualquier API que no requiera autenticación)

4. Ejecútalo

python src/server.py

Conectar con Claude Desktop

Añade una entrada a tu 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"]
    }
  }
}

Las variables de entorno se leen desde .env (mediante python-dotenv, resuelto relativo a la raíz del proyecto independientemente del directorio de trabajo del proceso), así que nada sensible necesita ir en la configuración de Claude.

Instalaciones de Claude Desktop desde Microsoft Store (MSIX): el archivo de configuración no está en la ruta habitual %APPDATA%\Claude\ — está en un entorno aislado bajo %LOCALAPPDATA%\Packages\<Claude package id>\LocalCache\Roaming\Claude\claude_desktop_config.json. Cierra completamente Claude Desktop desde la bandeja del sistema (no solo la ventana) antes de editarlo, y luego relánzalo.

Notas de seguridad

• Todas las consultas usan SQL parametrizado ($1, $2, ...) — sin SQL construido por cadenas, así que no hay riesgo de inyección desde los argumentos de las herramientas.

• run_query solo permite sentencias SELECT. Las escrituras pasan por las herramientas CRUD dedicadas en su lugar, lo que supone una superficie deliberadamente más reducida para un cliente impulsado por LLM.

• bookmarks_app es un rol no superusuario limitado a la base de datos bookmarks — el servidor nunca se conecta como superusuario de Postgres.

• .env está en gitignore. Nunca subas credenciales reales — usa .env.example como plantilla.