Construa seu primeiro servidor MCP em Python: dê suas próprias anotações ao Claude

Construa seu primeiro servidor MCP em Python: dê a Claude suas próprias anotações

Um guia para iniciantes sobre o Protocolo de Contexto do Modelo. Construa um verdadeiro servidor MCP em cerca de sessenta linhas de Python com uv e o SDK oficial, exponha duas ferramentas através do stdio e conecte-o ao Claude Code com um comando. Inclui a armadilha do stdout que se esconde atrás do buffer de bloco e só te ataca mais tarde.

peculiarengineer.com

Há 48 postagens neste site. Eu escrevi cada uma delas para nunca ter que pesquisar a mesma coisa duas vezes, e funciona: quando preciso da sintaxe do Netplan ou da exata ufw invocação, venho aqui em vez de me perder no Stack Overflow.

A parte irritante é que o modelo com o qual estou falando não leu nada disso. Ele conhece a forma geral do Netplan, não a versão que eu decidi após a terceira vez que me prejudicou. Posso colar um post na janela de chat, e eu já fiz isso, muitas vezes. Mas colar não é um sistema. É algo que você faz novamente a cada sessão, para sempre, e só funciona quando você já sabe qual post precisava.

O que eu realmente quero é uma porta. Deixe o modelo bater quando quiser algo, e deixe-o ler as anotações por conta própria.

Essa porta é o Protocolo de Contexto do Modelo, e a parte útil não é o protocolo. É que você escreve a integração uma vez. Sem o MCP, dar a um modelo acesso às suas anotações significa uma integração sob medida para cada ferramenta por cliente: uma para o Claude Code, outra para o aplicativo de desktop, outra para o que quer que você use no próximo ano. Com o MCP, você escreve um servidor que sabe como pesquisar suas anotações, e cada cliente que fala o protocolo pode chamá-lo. O servidor não sabe nem se importa quem está perguntando.

Este post constrói esse servidor. São cerca de sessenta linhas de Python.

TL;DR uv add "mcp[cli]", decore duas funções com @mcp.tool(), termine o arquivo com mcp.run(transport="stdio"), e registre-o com claude mcp add notes -- uv run --directory /abs/path server.py. Use um caminho absoluto ou não se conectará, e nunca print() para stdout, porque stdout é o transporte.

Antes de começar

Você precisa de uv e Claude Code. Essa é toda a lista. Não há servidor para implantar, nenhum Docker, nenhuma porta para abrir. Um servidor MCP local é apenas um programa que o Claude Code inicia como um subprocesso e se comunica através de stdin e stdout.

Esse último ponto vale a pena refletir, porque é a coisa que as pessoas esperam que seja complicada e não é. O MCP define dois transportes. Streamable HTTP é para servidores remotos que muitos clientes se conectam pela rede, e vem com toda a história de autenticação. stdio é para servidores locais, e é um pipe. Seu processo, o processo do cliente, JSON indo e voltando. Ninguém está ouvindo em uma porta e nada está exposto.

Tudo abaixo é stdio. É o lugar certo para começar, e para um servidor que lê arquivos no seu próprio laptop, pode ser o lugar certo para ficar.

O que você está construindo

Duas ferramentas:

• search_notes(query) encontra postagens que contêm uma frase e retorna seus slugs e títulos.
• get_note(slug) retorna um post inteiro.

Essa divisão importa mais do que parece. A pesquisa retorna uma lista pequena para que o modelo possa escolher, depois busca apenas o que deseja. Se search_notes retornasse os corpos completos dos posts, uma consulta de três palavras despejaria 40.000 palavras na janela de contexto e o modelo se afogaria antes de começar.

Estou apontando isso para meu blog porque é o que eu tenho. Aponte NOTES para qualquer pasta de markdown e funcionará da mesma forma. Essa é a ideia toda.

Configure o projeto

mkdir mcp-notes && cd mcp-notes
uv init .
uv add "mcp[cli]"

mcp[cli] é o SDK oficial do Python. O cli extra traz as ferramentas de desenvolvimento, que você vai querer mais tarde.

O servidor

Aqui está tudo, server.py:

"""Um servidor MCP que permite que Claude leia meus posts de blog.

Duas ferramentas: search_notes encontra postagens que contêm uma frase, get_note retorna um
post inteiro. Aponte NOTES para qualquer pasta de markdown e funciona da mesma forma.
"""

import sys
from pathlib import Path

from mcp.server.fastmcp import FastMCP

NOTES = Path.home() / "projects/peculiarengineer/src/content/blog"

mcp = FastMCP("notes")


def _posts() -> list[Path]:
    return sorted(NOTES.glob("*.md")) + sorted(NOTES.glob("*.mdx"))


def _title(text: str, fallback: str) -> str