local-pinboard-mcp

Servidor MCP Local Pinboard

Um servidor Model Context Protocol hospedado localmente que conecta sua conta Pinboard a qualquer assistente de IA compatível com MCP (como Claude Desktop, Cursor ou ferramentas similares).

Esta integração usa a API do Pinboard (v1) com esquemas TypeScript/Zod estritamente tipados para permitir que seu assistente de IA gerencie seus favoritos, tags e notas — sem expor credenciais externamente ou depender de serviços de terceiros.

Você pode usar o arquivo MCPB empacotado para começar rapidamente, ou clonar o repositório para construir o seu próprio. O código-fonte é aberto, local e auditável.

Recursos

Uma vez conectado, seu assistente de IA pode usar as seguintes ferramentas:

get_recent_posts

Liste seus favoritos Pinboard mais recentes, opcionalmente filtrados por até três tags.

Parâmetro	Tipo	Descrição
tag	string[]?	Filtrar por até 3 tags
count	number?	Número de resultados a retornar (padrão 15, máximo 100)

get_posts

Recupere favoritos que correspondam a uma tag, uma data específica ou uma URL específica.

Parâmetro	Tipo	Descrição
tag	string[]?	Filtrar por até 3 tags
dt	string?	Retornar posts adicionados nesta data (AAAA-MM-DD)
url	string?	Retornar o post para esta URL exata
meta	boolean?	Incluir hash de metadados de detecção de alterações

get_all_posts

Recupere todos os favoritos da sua conta Pinboard. Limitado a uma vez a cada 5 minutos.

Parâmetro	Tipo	Descrição
tag	string[]?	Filtrar por até 3 tags
start	number?	Deslocamento para paginação
results	number?	Número máximo de posts a retornar
fromdt	string?	Retornar apenas posts criados após esta data/hora (UTC)
todt	string?	Retornar apenas posts criados antes desta data/hora (UTC)

add_post

Adicionar ou substituir um favorito. URL e título são obrigatórios. Por padrão, substitui qualquer favorito existente para a mesma URL.

Parâmetro	Tipo	Descrição
url	string	A URL a favoritar (obrigatório)
title	string	Título do favorito (obrigatório)
description	string?	Notas estendidas ou descrição
tags	string[]?	Tags a aplicar. Tags que começam com . são privadas
shared	boolean?	Defina como false para tornar o favorito privado
toread	boolean?	Defina como true para marcar como não lido/para ler
replace	boolean?	Defina como false para pular se o favorito já existir
dt	string?	Carimbo de data/hora de criação em formato UTC ISO 8601

delete_post

Excluir permanentemente um favorito pela sua URL. Esta ação não pode ser desfeita.

Parâmetro	Tipo	Descrição
url	string	A URL do favorito a excluir permanentemente

suggest_tags

Retornar tags populares (em todo o site) e recomendadas (do seu histórico) para uma determinada URL.

Parâmetro	Tipo	Descrição
url	string	A URL para obter sugestões de tags

get_tags

Obtenha todas as suas tags do Pinboard com suas contagens de uso. Sem parâmetros.

rename_tag

Renomeie uma tag em todos os favoritos, ou mescle-a em uma tag existente.

Parâmetro	Tipo	Descrição
old_name	string	O nome da tag atual
new_name	string	O novo nome da tag

delete_tag

Exclua uma única tag da sua conta. Remove a tag de todos os favoritos, mas não os exclui.

Parâmetro	Tipo	Descrição
tag	string	O nome da tag a excluir

list_notes

Liste todas as suas notas (sem o corpo do texto). Sem parâmetros. A criação/edição de notas não é suportada na API v1.

get_note

Busque uma nota específica incluindo seu corpo de texto completo.

Parâmetro	Tipo	Descrição
id	string	O ID hexadecimal da nota

get_last_update

Retorna o horário da alteração mais recente de favoritos. Use isso para verificar se os dados mudaram desde sua última busca. Sem parâmetros.

---

Abordagem de Segurança

Este servidor usa transporte stdio exclusivamente — ele nunca expõe uma porta HTTP externa. A comunicação é estritamente entre sua máquina local e os endpoints oficiais do api.pinboard.in.

Seu token de API é passado ao Pinboard via parâmetro de consulta auth_token conforme exigido pela API v1. Para garantir privacidade absoluta, o servidor é projetado para interceptar e sanitizar mensagens de erro em nível de rede para evitar que seu token vaze acidentalmente nos logs locais do Claude Desktop ou Cursor em caso de falha de rede.

Respostas de erro são truncadas com segurança, e caminhos de entrada como tags e IDs hexadecimais são estritamente verificados via regex do Zod antes que as requisições sejam feitas.

---

Instalação e Configuração

0. Baixe o arquivo MCPB mais recente

Baixar dos lançamentos do GitHub

Arraste o arquivo .mcpb da sua pasta de downloads para a área de trabalho ou navegador de arquivos do seu assistente de IA. O assistente deve reconhecê-lo como um servidor MCP e solicitar que você o carregue.

Ou...

1. Requisitos

Certifique-se de ter instalado Node.js (versão 22+ recomendada) e npm na sua máquina local.

2. Obtenha seu Token de API do Pinboard

1. Entre na sua conta Pinboard.
2. Vá para Configurações → Senha.
3. Seu token de API é exibido nessa página no formato username:HEXTOKEN.
4. Copie-o com segurança.

3. Configuração Local do Projeto

Clone o repositório e instale as dependências necessárias:

npm install

Copie o arquivo de exemplo de variáveis de ambiente:

cp .env.example .env

Abra .env no seu editor de texto e cole seu token de API:

PINBOARD_API_TOKEN=username:YOURHEXTOKEN

4. Compile o Projeto

Compile TypeScript para JavaScript:

npm run build

---

Conectando a um Cliente MCP

Este servidor funciona com qualquer cliente compatível com MCP. Abaixo está um exemplo usando Claude Desktop.

Claude Desktop

1. Abra o Claude Desktop e escolha Configurações → Desenvolvedor → Editar Config para abrir claude_desktop_config.json.

2. Adicione isso à seção mcpServers, corrigindo o caminho para o arquivo index.js compilado e adicionando seu próprio 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"
      }
    }
  }
}

3. Reinicie o Claude Desktop. As novas ferramentas aparecerão instantaneamente e você pode começar a perguntar coisas como "Mostre-me meus favoritos não lidos recentes" ou "Pesquise meus favoritos por tutoriais de React".

Para outros clientes MCP, consulte a documentação deles sobre como registrar um servidor stdio local apontando para dist/index.js com as variáveis de ambiente necessárias.

---

Desenvolvimento e Testes

Este projeto é construído usando TypeScript, @modelcontextprotocol/sdk e análise Zod.

Se você estiver desenvolvendo novas ferramentas ou fazendo ajustes:

1. Compile: Sempre execute npm run build após fazer modificações.
2. Testes: Execute a suíte de testes Vitest:

npm test

Pull requests são bem-vindos! Por favor, abra uma issue primeiro para discutir o que você gostaria de alterar.