mcp-notes-server

mcp-notes-server

Um servidor Model Context Protocol (MCP) gratuito e de código aberto, mínimo, em Python, que dá a qualquer assistente de IA compatível com MCP um bloco de notas persistente: crie notas, liste-as e pesquise-as — armazenadas em um arquivo JSON local simples que você controla.

Construído com o SDK oficial mcp Python (FastMCP). Sem banco de dados, sem nuvem, sem contas. Suas notas nunca saem da sua máquina.

Ferramentas

Ferramenta	O que faz
create_note	Cria uma nota com um título (obrigatório, ≤120 caracteres) e corpo (≤10.000 caracteres). Retorna o registro salvo com id e timestamps.
list_notes	Lista as notas salvas, das mais recentes para as mais antigas (limite configurável, 1–500).
search_notes	Pesquisa por palavra-chave sem diferenciar maiúsculas de minúsculas em títulos e corpos.

Início rápido

git clone <this-repo-url>
cd mcp-notes-server
pip install -r requirements.txt
python server.py

O servidor fala MCP via stdio. Conecte-o a qualquer host MCP — veja os exemplos de configuração abaixo e em examples/.

Claude Desktop

Adicione ao seu claude_desktop_config.json (veja examples/claude_desktop_config.example.json):

{
  "mcpServers": {
    "notes-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-notes-server/server.py"]
    }
  }
}

Host MCP genérico

Veja examples/mcp-client-config.generic.json — o mesmo padrão de comando/argumentos via stdio funciona para a maioria dos hosts.

Experimente

1. Conecte seu host MCP e peça: "Crie uma nota intitulada 'Lista de compras' com leite, ovos e café."
2. Peça: "Pesquise nas minhas notas por ovos."
3. Abra notes.json (criado automaticamente ao lado de server.py) para ver o armazenamento bruto — é apenas JSON.

Como funciona

• Os utilitários de armazenamento carregam/salvam um único arquivo notes.json; os salvamentos são atômicos (grava em um arquivo temporário e depois substitui).
• Cada ferramenta valida sua entrada (título obrigatório e com limite de tamanho, corpo com limite de tamanho, consulta de pesquisa obrigatória).
• As funções das ferramentas são funções Python comuns decoradas com @mcp.tool() — as anotações de tipo se tornam os esquemas de entrada das ferramentas. O servidor inteiro é um único arquivo legível (~150 linhas), feito para ser copiado e adaptado.

Execute o teste de fumaça (sem necessidade de host MCP):

python tests/smoke_test.py

Verificado de ponta a ponta sobre o protocolo MCP real (stdio, SDK oficial v1.x) — ferramentas listadas, nota criada, pesquisada e listada: veja tests/mcp_e2e_test.py e execute você mesmo após pip install -r requirements.txt. Observe que os requisitos fixam mcp<2: o SDK 2.x renomeou o FastMCP, e este código tem como alvo a API v1.

Escopo e segurança

• Somente local. Este servidor lê/grava um arquivo JSON em sua própria pasta. Ele não faz chamadas de rede e não tem ferramenta de exclusão — por design, como um padrão inicial.
• Trate-o como uma base de aprendizado/prototipagem, não como um serviço de produção endurecido: sem autenticação (servidores stdio são iniciados pelo seu host como seu usuário), sem bloqueio de concorrência além da substituição atômica de arquivos.

Obtenha o pacote completo

Este servidor gratuito é um dos três iniciadores do pacote MCP Server Starter Templates — o pacote completo adiciona um servidor de consulta SQLite somente leitura (com proteção testada contra injeção de SQL: validação somente SELECT) e um esqueleto de servidor de resumo web, além de configurações de cliente para os três, uma lista de verificação de testes e notas de segurança para levar servidores MCP à produção.

→ MCP Server Starter Templates (e mais ferramentas de agentes de IA: kits de teste AgentProof, kits de avaliação LLM/RAG, conjuntos de dados verificados para agentes): bradray2.gumroad.com

Amostras gratuitas dos kits pagos estão no repositório complementar, ai-agent-tools-free-samples.

Licença

MIT — veja LICENSE. Use, faça fork, publique.

Copyright (c) 2026 Brad Lucas.