local-pinboard-mcp

Un servidor MCP local y seguro para conectar tu asistente de IA a tus marcadores de Pinboard.

Documentación

Servidor MCP de Local Pinboard

Un servidor Model Context Protocol alojado localmente que conecta tu cuenta de Pinboard con cualquier asistente de IA compatible con MCP (como Claude Desktop, Cursor o herramientas similares).

Esta integración utiliza la API de Pinboard (v1) con esquemas TypeScript/Zod estrictamente tipados para permitir que tu asistente de IA gestione tus marcadores, etiquetas y notas, sin exponer credenciales externamente ni depender de servicios de terceros.

Puedes usar el archivo MCPB empaquetado para ponerte en marcha rápidamente, o clonar el repositorio para construir el tuyo propio. El código fuente es abierto, local y auditable.

Capacidades

Una vez conectado, tu asistente de IA puede usar las siguientes herramientas:

`get_recent_posts`

Lista tus marcadores de Pinboard más recientes, opcionalmente filtrados por hasta tres etiquetas.

Parámetro	Tipo	Descripción
`tag`	string[]?	Filtrar por hasta 3 etiquetas
`count`	number?	Número de resultados a devolver (por defecto 15, máximo 100)

`get_posts`

Recupera marcadores que coincidan con una etiqueta, una fecha específica o una URL específica.

Parámetro	Tipo	Descripción
`tag`	string[]?	Filtrar por hasta 3 etiquetas
`dt`	string?	Devuelve publicaciones añadidas en esta fecha (AAAA-MM-DD)
`url`	string?	Devuelve la publicación para esta URL exacta
`meta`	boolean?	Incluye hash de metadatos de detección de cambios

`get_all_posts`

Recupera todos los marcadores de tu cuenta de Pinboard. Limitado a una vez cada 5 minutos.

Parámetro	Tipo	Descripción
`tag`	string[]?	Filtrar por hasta 3 etiquetas
`start`	number?	Desplazamiento para paginación
`results`	number?	Número máximo de publicaciones a devolver
`fromdt`	string?	Devuelve solo publicaciones creadas después de esta fecha/hora (UTC)
`todt`	string?	Devuelve solo publicaciones creadas antes de esta fecha/hora (UTC)

`add_post`

Añade o reemplaza un marcador. La URL y el título son obligatorios. Por defecto, reemplaza cualquier marcador existente para la misma URL.

Parámetro	Tipo	Descripción
`url`	string	La URL a marcar (obligatoria)
`title`	string	Título del marcador (obligatorio)
`description`	string?	Notas extendidas o descripción
`tags`	string[]?	Etiquetas a aplicar. Las etiquetas que comienzan con `.` son privadas
`shared`	boolean?	Establecer en `false` para hacer el marcador privado
`toread`	boolean?	Establecer en `true` para marcar como no leído/para leer
`replace`	boolean?	Establecer en `false` para omitir si el marcador ya existe
`dt`	string?	Marca de tiempo de creación en formato ISO 8601 UTC

`delete_post`

Elimina permanentemente un marcador por su URL. Esta acción no se puede deshacer.

Parámetro	Tipo	Descripción
`url`	string	La URL del marcador a eliminar permanentemente

`suggest_tags`

Devuelve etiquetas populares (de todo el sitio) y recomendadas (según tu historial) para una URL determinada.

Parámetro	Tipo	Descripción
`url`	string	La URL para obtener sugerencias de etiquetas

`get_tags`

Obtén todas tus etiquetas de Pinboard con sus contadores de uso. Sin parámetros.

`rename_tag`

Renombra una etiqueta en todos los marcadores, o fúndela en una etiqueta existente.

Parámetro	Tipo	Descripción
`old_name`	string	El nombre de la etiqueta actual
`new_name`	string	El nuevo nombre de la etiqueta

`delete_tag`

Elimina una sola etiqueta de tu cuenta. Elimina la etiqueta de todos los marcadores pero no los borra.

Parámetro	Tipo	Descripción
`tag`	string	El nombre de la etiqueta a eliminar

`list_notes`

Lista todas tus notas (sin el texto del cuerpo). Sin parámetros. La creación/edición de notas no es compatible con la API v1.

`get_note`

Obtiene una nota específica incluyendo el texto completo de su cuerpo.

Parámetro	Tipo	Descripción
`id`	string	El ID hexadecimal de la nota

`get_last_update`

Devuelve la hora del cambio de marcador más reciente. Úsalo para comprobar si los datos han cambiado desde tu última consulta. Sin parámetros.

Enfoque de Seguridad

Este servidor utiliza exclusivamente transporte stdio — nunca expone un puerto HTTP externo. La comunicación es estrictamente entre tu máquina local y los endpoints oficiales de api.pinboard.in.

Tu token de API se pasa a Pinboard mediante el parámetro de consulta auth_token según lo requiere la API v1. Para garantizar una privacidad absoluta, el servidor está diseñado para interceptar y sanitizar los mensajes de error a nivel de red para evitar que tu token se filtre accidentalmente en los registros locales de Claude Desktop o Cursor si ocurre una falla de red.

Las respuestas de error se truncan de forma segura, y las rutas de entrada como etiquetas e IDs hexadecimales se verifican estrictamente mediante expresiones regulares de Zod antes de realizar las solicitudes.

Instalación y Configuración

0. Descarga el archivo MCPB más reciente

Descargar desde GitHub Releases

Arrastra el archivo .mcpb desde tu carpeta de descargas al escritorio o al explorador de archivos de tu asistente de IA. El asistente debería reconocerlo como un servidor MCP y pedirte que lo cargues.

O...

1. Requisitos

Asegúrate de tener instalado Node.js (versión 22+ recomendada) y npm en tu máquina local.

2. Obtén tu Token de API de Pinboard

Inicia sesión en tu cuenta de Pinboard.
Ve a Configuración → Contraseña.
Tu token de API se muestra en esa página en el formato username:HEXTOKEN.
Cópialo de forma segura.

3. Configuración del Proyecto Local

Clona el repositorio e instala las dependencias requeridas:

npm install

Copia el archivo de ejemplo de variables de entorno:

cp .env.example .env

Abre .env en tu editor de texto y pega tu token de API:

PINBOARD_API_TOKEN=username:YOURHEXTOKEN

4. Compila el Proyecto

Compila TypeScript a JavaScript:

npm run build

Conexión a un Cliente MCP

Este servidor funciona con cualquier cliente compatible con MCP. A continuación se muestra un ejemplo usando Claude Desktop.

Claude Desktop

Abre Claude Desktop y elige Configuración → Desarrollador → Editar Config para abrir claude_desktop_config.json.
Añade esto a la sección mcpServers, corrigiendo la ruta al archivo index.js compilado y añadiendo tu propio token de API:

{
  "mcpServers": {
    "local-pinboard": {
      "command": "node",
      "args": ["/absolute/path/to/your/local-pinboard-mcp/dist/index.js"],
      "env": {
        "PINBOARD_API_TOKEN": "username:YOURHEXTOKEN"
      }
    }
  }
}

Reinicia Claude Desktop. Las nuevas herramientas aparecerán al instante y podrás empezar a preguntar cosas como "Muéstrame mis marcadores recientes no leídos" o "Busca en mis marcadores tutoriales de React".

Para otros clientes MCP, consulta su documentación sobre cómo registrar un servidor stdio local apuntando a dist/index.js con las variables de entorno requeridas.

Desarrollo y Pruebas

Este proyecto está construido usando TypeScript, @modelcontextprotocol/sdk y análisis Zod.

Si estás desarrollando nuevas herramientas o haciendo ajustes:

Compilar: Asegúrate siempre de ejecutar npm run build después de hacer modificaciones.
Pruebas: Ejecuta el conjunto de pruebas de Vitest:

npm test

¡Las solicitudes de extracción son bienvenidas! Por favor, abre primero un issue para discutir lo que te gustaría cambiar.