MarkItDown MCP: primeiro converta uma página https pública em Markdown

Para quem

Para converter nesta máquina um documento ou página web em Markdown e entregá-lo a um agente confiável. A evidência afirma: markitdown-mcp oferece servidores leves STDIO, Streamable HTTP e SSE, e expõe só uma ferramenta, convert_to_markdown(uri); a uri pode ser http:, https:, file: ou data:.

Foi pensado para agentes locais confiáveis. Não há autenticação; as permissões do processo igualam o usuário que o iniciou. convert_to_markdown pode ler qualquer arquivo que esse usuário possa ler e buscar dados de rede. Não abra para clientes não confiáveis numa máquina compartilhada.

A evidência não lista clientes. Não vincule HTTP/SSE a algo que não seja localhost, salvo se você entender o risco.

Primeira tentativa em 3 minutos

Siga o caminho principal pip; não trate Docker como instalação principal:

pip install markitdown-mcp
markitdown-mcp

STDIO é o padrão. Quando precisar de HTTP/SSE, a evidência dá:

markitdown-mcp --http --host 127.0.0.1 --port 3001

Na primeira vez use STDIO e mantenha o bind nesta máquina.

Pré-requisitos: Python/pip locais funcionam; a primeira conversão é uma página https: à qual você tem acesso público — não alimente primeiro um arquivo de chaves nem um file: interno. Isso lerá a URI indicada e pode sair para a rede.

Onde configurar: no MCP do cliente, command = markitdown-mcp (stdio). Abra HTTP só depois de entender que qualquer processo desta máquina pode acessar.

Primeira chamada de baixo risco: convert_to_markdown(uri) com uma uri https: pública. Não use file: apontando para o diretório home ou segredos, e não mude --host.

Sinal de sucesso: a ferramenta devolve o Markdown convertido dessa URI. Se o processo não subir, confira primeiro o nome do pacote pip; não mude para Docker.

Casos de uso

Caso 1: converter uma página pública em Markdown. Chame convert_to_markdown com uri https:. A evidência só garante que aceita esse tipo de URI; não documenta estilo de saída, teto de tamanho nem muros de login. O que se confirma: você vê o texto convertido.

Caso 2: converter um arquivo local em Markdown. uri file:. Lê o disco com as permissões do usuário do servidor; no modo HTTP/SSE, outros processos desta máquina podem disparar a mesma leitura. Confirme primeiro que o caminho não tem segredos. Uma URI data: também entra na conversão; a evidência não documenta limite de comprimento. O build Docker é docker build -t markitdown-mcp:latest . e depois docker run -it --rm markitdown-mcp:latest, que não é o mesmo caminho principal que pip.

Limites de uso

Sem autenticação; as permissões igualam o usuário que inicia. HTTP/SSE liga por padrão a localhost e ainda assim outros processos ou usuários desta máquina podem alcançar. Não ligue a outra NIC. A única ferramenta é convert_to_markdown. Ela lê arquivos e dados de rede que o usuário puder ler — não é risco zero nem uma escrita reversível: a evidência não tem undo. Não trate Docker e pip como instalações principais em paralelo.