tutorial · 2026-07-11

MCP Server Windows — Crie ferramentas personalizadas para agentes de IA

Tutorial completo de como criar um MCP server no Windows com Node.js. Aprenda a construir ferramentas personalizadas para Claude Code e outros agentes de IA usando o Model Context Protocol.

Você já imaginou dar superpoderes ao seu agente de IA — acesso a uma API interna, consulta a um banco local, automação de tarefas repetitivas do sistema? Com o Model Context Protocol (MCP), isso é possível. Neste tutorial, você vai aprender a criar seu primeiro MCP server Windows do zero usando Node.js, conectar ao Claude Code e construir ferramentas que interagem com o sistema operacional.

Sumário

O que é MCP (Model Context Protocol) e por que criar seus próprios servers?
Pré-requisitos no Windows: Node.js, npm, Claude Code configurado
Criando seu primeiro MCP server do zero (exemplo: ferramenta de busca local)
Conectando o MCP server ao Claude Code
Exemplo real: MCP server para APIs do Windows (sistema de arquivos, clipboard)
Cenários de uso avançado
Debugging e logs do MCP server no Windows
Publicando e compartilhando seu MCP server
FAQ
Comece agora

O que é MCP (Model Context Protocol) e por que criar seus próprios servers?

O Model Context Protocol é um padrão aberto desenvolvido pela Anthropic que permite que agentes de IA se conectem a ferramentas externas de forma padronizada. Pense no MCP como o equivalente ao protocolo USB para agentes: em vez de cada fabricante criar seu próprio conector proprietário, o MCP define uma interface única para comunicação entre o modelo de IA e qualquer ferramenta externa.

Como funciona?

Um MCP server é um processo leve que expõe ferramentas (tools) e recursos (resources) para um cliente MCP — no caso, o Claude Code. A comunicação acontece via JSON-RPC sobre stdin/stdout ou SSE (Server-Sent Events). Quando o agente identifica que precisa de uma informação ou ação que não está no seu treinamento, ele chama a ferramenta apropriada do MCP server.

Por que criar seu próprio MCP server?

Os MCP servers públicos atendem cenários genéricos, mas o valor real está nos servers customizados:

Integração com APIs internas da sua empresa (ERP, CRM, sistemas legados)
Acesso a bancos de dados locais (SQLite, PostgreSQL) sem expor credenciais na nuvem
Automação de tarefas específicas do Windows (manipular arquivos, clipboard, processos)
Ferramentas proprietárias que seu time usa diariamente

Ao criar um MCP server Windows, você transforma seu agente de IA em um assistente que entende e opera o sistema operacional como um desenvolvedor experiente.

Pré-requisitos no Windows: Node.js, npm, Claude Code configurado

Antes de começar, verifique se seu ambiente Windows está pronto:

1. Node.js (v18 ou superior)

O MCP SDK para TypeScript/JavaScript roda sobre Node.js. Instale a versão LTS mais recente:

winget install OpenJS.NodeJS.LTS # ou nvm install lts

Confirme a instalação:

node --version # v18.x ou v20.x npm --version # 9.x ou 10.x

2. Claude Code configurado no Windows

Você precisa do Claude Code rodando no terminal. Se ainda não configurou:

npm install -g @anthropic-ai/claude-code # ou via npx npx @anthropic-ai/claude-code

Configure sua chave de API da Anthropic como variável de ambiente:

$env:ANTHROPIC_API_KEY="sua-chave-aqui"

Para persistir a variável, adicione ao perfil do PowerShell ($PROFILE) ou configure via interface do Windows (Configurações > Sistema > Sobre > Configurações avançadas do sistema > Variáveis de Ambiente).

3. TypeScript e ts-node (opcional, mas recomendado)

npm install -g typescript ts-node

4. Um editor de código

Você pode usar qualquer editor. O VSCode ou o próprio Claude Code servem bem para este tutorial.

*Verificação do Node.js e npm no PowerShell do Windows 11*

Criando seu primeiro MCP server do zero (exemplo: ferramenta de busca local)

Vamos construir um MCP server Windows funcional que implementa uma ferramenta de busca local. A ideia é permitir que qualquer agente de IA conectado ao server possa pesquisar arquivos no sistema.

Estrutura do projeto

mkdir meu-mcp-server cd meu-mcp-server npm init -y

Instalando o MCP SDK

npm install @modelcontextprotocol/sdk npm install typescript @types/node --save-dev

Configurando TypeScript

Crie um tsconfig.json:

{ "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "esModuleInterop": true, "strict": true, "outDir": "./dist", "rootDir": "./src" }, "include": ["src/**/*"] }

Criando o servidor

Crie src/index.ts:

import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js"; import { execSync } from "child_process"; import * as fs from "fs"; import * as path from "path"; // Definição das ferramentas do servidor const server = new Server( { name: "windows-local-search", version: "1.0.0", }, { capabilities: { tools: {}, }, } ); // Handler para listar as ferramentas disponíveis server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "search_files", description: "Busca arquivos no sistema Windows por nome. Retorna caminhos, tamanhos e datas de modificação.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Termo de busca (nome do arquivo ou padrão, ex.: *.txt)", }, directory: { type: "string", description: "Diretório base para busca (padrão: diretório atual)", }, maxResults: { type: "number", description: "Número máximo de resultados (padrão: 20)", default: 20, }, }, required: ["query"], }, }, { name: "read_file", description: "Lê o conteúdo de um arquivo no sistema Windows.", inputSchema: { type: "object", properties: { path: { type: "string", description: "Caminho completo do arquivo", }, encoding: { type: "string", description: "Codificação do arquivo (padrão: utf-8)", default: "utf-8", }, }, required: ["path"], }, }, ], }; }); // Handler para executar as ferramentas server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; if (name === "search_files") { const query = String(args?.query || ""); const directory = String(args?.directory || process.cwd()); const maxResults = Number(args?.maxResults) || 20; // Para Windows, usamos PowerShell para busca mais flexível const psCommand = `Get-ChildItem -Path "${directory}" -Filter "${query}" -Recurse -ErrorAction SilentlyContinue | Select-Object FullName, Length, LastWriteTime | ConvertTo-Json`; try { const output = execSync( `powershell -Command "& { ${psCommand} }"`, { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 } ); const results = JSON.parse(output); const files = Array.isArray(results) ? results.slice(0, maxResults) : [results]; return { content: [ { type: "text", text: JSON.stringify( files.map((f: any) => ({ caminho: f.FullName, tamanho_bytes: f.Length, modificado_em: f.LastWriteTime, })), null, 2 ), }, ], }; } catch (error: any) { return { content: [ { type: "text", text: `Erro na busca: ${error.message}`, }, ], isError: true, }; } } if (name === "read_file") { const filePath = String(args?.path || ""); try { const content = fs.readFileSync(filePath, "utf-8"); const stats = fs.statSync(filePath); return { content: [ { type: "text", text: `--- ${filePath} ---\nTamanho: ${stats.size} bytes\nModificado: ${stats.mtime}\n\n${content}`, }, ], }; } catch (error: any) { return { content: [ { type: "text", text: `Erro ao ler arquivo: ${error.message}`, }, ], isError: true, }; } } throw new Error(`Ferramenta desconhecida: ${name}`); }); // Inicializa o servidor async function main() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("MCP Server Windows rodando via stdio"); } main().catch((error) => { console.error("Erro fatal:", error); process.exit(1); });

Compilando o TypeScript

npx tsc

Isso gera os arquivos compilados em dist/index.js.

Testando o servidor localmente

node dist/index.js

Você verá a mensagem: MCP Server Windows rodando via stdio. O servidor está ativo e aguardando comunicação via stdin/stdout.

Imagem sugerida: Diagrama mostrando a arquitetura do MCP — agente de IA se comunicando via JSON-RPC com o MCP server, que por sua vez chama APIs do Windows e sistemas externos.

Conectando o MCP server ao Claude Code

Agora que seu servidor está funcionando, vamos conectá-lo ao Claude Code.

Configuração via claude.json

O Claude Code lê um arquivo de configuração no diretório do projeto ou global. Crie claude.json na raiz do seu projeto:

{ "mcpServers": { "windows-local-search": { "command": "node", "args": ["C:\\caminho\\completo\\ate\\meu-mcp-server\\dist\\index.js"], "env": {} } } }

Substitua o caminho pelo diretório real do seu projeto. No Windows, lembre-se de usar barras invertidas duplicadas (\\) ou barras normais (/).

Configuração global

Se quiser que o MCP server esteja disponível em todos os projetos, edite o arquivo de configuração global do Claude Code, geralmente em:

%APPDATA%\Claude\config.json

{ "mcpServers": { "windows-local-search": { "command": "node", "args": ["C:/dev/meu-mcp-server/dist/index.js"] } } }

Testando a integração

Abra o Claude Code em qualquer diretório e pergunte:

"Procure por todos os arquivos .tsx no diretório atual"

O Claude Code identificará que precisa executar a ferramenta search_files e chamará seu MCP server automaticamente. A resposta incluirá a lista de arquivos encontrados.

# No terminal do Claude Code claude > Procure por arquivos .log na pasta C:\Logs e me mostre os 5 maiores

*Claude Code chamando a ferramenta search_files do MCP server Windows*

Exemplo real: MCP server para APIs do Windows (sistema de arquivos, clipboard)

Vamos expandir nosso MCP server com ferramentas que interagem diretamente com APIs nativas do Windows. Este é um MCP server Windows que realmente entende do sistema.

Ferramenta de clipboard

Adicione ao ListToolsRequestSchema:

{ name: "get_clipboard", description: "Obtém o conteúdo atual da área de transferência do Windows.", inputSchema: { type: "object", properties: {}, required: [], }, },

E no CallToolRequestSchema:

if (name === "get_clipboard") { try { // PowerShell para acessar o clipboard do Windows const output = execSync( `powershell -Command "& { Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::GetText() }"`, { encoding: "utf-8" } ); return { content: [ { type: "text", text: output.trim() || "(clipboard vazio)", }, ], }; } catch (error: any) { return { content: [ { type: "text", text: `Erro ao acessar clipboard: ${error.message}`, }, ], isError: true, }; } }

Ferramenta de informações do sistema

{ name: "system_info", description: "Obtém informações do sistema Windows: CPU, memória, disco, SO.", inputSchema: { type: "object", properties: {}, required: [], }, },

if (name === "system_info") { try { const cpu = execSync( `powershell -Command "& { Get-CimInstance Win32_Processor | Select-Object Name, NumberOfCores, MaxClockSpeed | ConvertTo-Json }"`, { encoding: "utf-8" } ); const memory = execSync( `powershell -Command "& { Get-CimInstance Win32_OperatingSystem | Select-Object TotalVisibleMemorySize, FreePhysicalMemory | ConvertTo-Json }"`, { encoding: "utf-8" } ); const disk = execSync( `powershell -Command "& { Get-CimInstance Win32_LogicalDisk -Filter 'DriveType=3' | Select-Object DeviceID, Size, FreeSpace | ConvertTo-Json }"`, { encoding: "utf-8" } ); return { content: [ { type: "text", text: JSON.stringify({ cpu: JSON.parse(cpu), memoria: JSON.parse(memory), disco: JSON.parse(disk), }, null, 2), }, ], }; } catch (error: any) { return { isError: true, content: [{ type: "text", text: `Erro: ${error.message}` }], }; } }

Compile e teste

npx tsc node dist/index.js

Agora seu MCP server Windows responde a perguntas como:

"Qual o uso de memória do sistema?"
"Cole o conteúdo da área de transferência neste arquivo"
"Encontre arquivos .exe modificados nos últimos 7 dias"

*MCP server Windows respondendo a comandos do sistema operacional via Claude Code*

Cenários de uso avançado

Em empresas, o MCP server vai além de ferramentas isoladas e se torna uma peça central de infraestrutura. Um dos casos mais comuns é a automação de esteiras de CI/CD. Imagine um agente que, ao detectar um commit com falha no repositório, aciona um MCP server conectado ao GitHub Actions ou Azure DevOps para reiniciar o pipeline, analisar logs de erro e sugerir correções automaticamente. Em vez de um desenvolvedor perder 30 minutos investigando uma build quebrada, o agente já entrega o diagnóstico e a solução proposta. Esse ciclo reduz o feedback loop de desenvolvimento e acelera entregas.

Outro cenário de alto impacto é a orquestração multiagente em ambientes DevOps. Um MCP server pode expor ferramentas de infraestrutura como Kubernetes, Terraform e Ansible para múltiplos agentes simultaneamente. Por exemplo, um agente verifica a saúde dos pods no cluster, outro consulta o estado dos recursos na AWS e um terceiro executa rollbacks quando necessário — tudo coordenado pelo mesmo protocolo. Essa arquitetura reduz o tempo médio de resposta a incidentes (MTTR) de horas para minutos, já que a detecção, diagnóstico e correção acontecem de forma automatizada e encadeada.

Na automação de processos internos, o MCP server atua como ponte entre sistemas legados e agentes modernos. Um banco, por exemplo, pode expor consultas a um mainframe via MCP, permitindo que agentes de IA extraiam relatórios de conformidade sem acesso direto ao sistema crítico. O protocolo adiciona uma camada de segurança e auditabilidade — toda chamada fica registrada em logs, facilitando a rastreabilidade exigida por auditorias e compliance regulatório.

Empresas de tecnologia também usam MCP para testes automatizados em larga escala. Um servidor pode controlar múltiplas máquinas Windows via PowerShell Remoting, executando suites de teste paralelas, coletando resultados e gerando relatórios consolidados. O agente coordena o ciclo completo — da execução à notificação da equipe — sem intervenção manual.

Por fim, o MCP server viabiliza assistentes internos personalizados: times de suporte consultam bases de conhecimento proprietárias, equipes de RH acessam sistemas de benefícios, e desenvolvedores buscam em repositórios internos — tudo com a mesma interface única do MCP. Isso unifica o ecossistema de ferramentas da empresa sob um protocolo padronizado, reduzindo a curva de aprendizado e aumentando a produtividade do time.

Debugging e logs do MCP server no Windows

Depurar um MCP server no Windows requer atenção redobrada porque a comunicação acontece via pipes (stdin/stdout). Qualquer console.log inadvertido quebra o protocolo JSON-RPC.

Regra de ouro: use stderr para logs

No seu código, sempre use console.error em vez de console.log para mensagens de depuração:

console.error("[DEBUG] search_files chamado com query:", query); // ✅ OK — stderr não interfere no protocolo

console.log("[DEBUG] search_files chamado"); // ❌ QUEBRA o protocolo!

Ativando logs detalhados

Adicione uma flag de debug ao seu servidor:

const DEBUG = process.env.MCP_DEBUG === "true"; // Uso: if (DEBUG) console.error("[MCP] Chamando ferramenta:", name);

No claude.json:

{ "mcpServers": { "windows-local-search": { "command": "node", "args": ["C:/dev/meu-mcp-server/dist/index.js"], "env": { "MCP_DEBUG": "true" } } } }

Testando o MCP server isoladamente

Use o mcp-cli para testar seu servidor sem o Claude Code:

npx @modelcontextprotocol/inspector node dist/index.js

Isso abre uma interface web em http://localhost:3001 onde você pode listar ferramentas, chamá-las manualmente e ver as respostas completas — fundamental para depurar erros de schema ou formatação.

Erros comuns no Windows

Problema	Causa	Solução
`stdout não é um TTY`	Caminho do Node.js incorreto	Use caminho absoluto no `claude.json`
`permissão negada`	PowerShell ExecutionPolicy	`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`
`JSON-RPC parse error`	`console.log` no código	Troque por `console.error`
Servidor não inicia	Porta ocupada (SSE)	Use stdio em vez de SSE

Imagem sugerida: Screenshot do MCP Inspector rodando no Windows, mostrando a interface web com a lista de ferramentas e um exemplo de chamada.

Publicando e compartilhando seu MCP server

Depois que seu MCP server Windows estiver funcionando, você pode compartilhá-lo de várias formas:

1. Pacote npm

Publique seu MCP server como pacote npm para instalação global:

// package.json { "name": "mcp-windows-tools", "version": "1.0.0", "bin": { "mcp-windows-tools": "./dist/index.js" }, "mcp": { "servers": { "windows-tools": { "command": "npx", "args": ["-y", "mcp-windows-tools"] } } } }

Publique com npm publish. Depois, qualquer pessoa pode instalar com:

// claude.json { "mcpServers": { "windows-tools": { "command": "npx", "args": ["-y", "mcp-windows-tools"] } } }

2. Repositório GitHub

Crie um repositório com:

Código-fonte completo com TypeScript
README.md com instruções de instalação e uso
Exemplos de configuração claude.json
Licença MIT para incentivar contribuições

3. Publicação em diretórios de MCP servers

A comunidade mantém listas curadas de MCP servers. Considere submeter seu server para:

github.com/modelcontextprotocol/servers — diretório oficial da Anthropic
mcpserver.com — diretório comunitário

Checklist de publicação

[ ] Código testado no Windows 11
[ ] Instruções claras de instalação
[ ] Schema das ferramentas documentado
[ ] Tratamento de erros implementado
[ ] Uso exclusivo de stderr para logs
[ ] Licença incluída

FAQ

O que é MCP server e para que serve?

MCP server é um processo que expõe ferramentas e recursos para agentes de IA via protocolo JSON-RPC. Ele permite que o Claude Code e outros agentes executem ações no mundo real — buscar arquivos, consultar APIs, acessar bancos de dados — indo além da geração de texto puro.

Preciso de um servidor na nuvem para rodar um MCP server?

Não. Um MCP server roda localmente na sua máquina Windows, como qualquer processo Node.js. A comunicação é via stdin/stdout ou SSE (Server-Sent Events). Nada precisa estar na nuvem — seus dados e credenciais ficam na sua máquina.

Quais linguagens suportam MCP server?

O SDK oficial da Anthropic tem versões para TypeScript/JavaScript e Python. Você também pode implementar o protocolo JSON-RPC manualmente em qualquer linguagem — Go, Rust, C#, Java — desde que consiga ler/escrever stdin/stdout.

O MCP server funciona com outros agentes além do Claude Code?

Sim. O protocolo MCP é aberto. Qualquer agente ou aplicação que implemente o lado cliente do protocolo pode se conectar. O Orquestra, por exemplo, suporta MCP servers nativamente, permitindo que você compartilhe as mesmas ferramentas entre Claude Code, Codex e outros agentes no mesmo canvas.

O MCP server é seguro?

A segurança depende de como você implementa. O protocolo em si não impõe restrições — cabe a você validar entradas, limitar o escopo das ferramentas e nunca expor credenciais. Um MCP server local é inerentemente mais seguro que uma API pública, já que só escuta no seu terminal.

Como faço para debugar um MCP server no Windows?

Use o MCP Inspector (npx @modelcontextprotocol/inspector) para testar ferramentas individualmente. Substitua console.log por console.error. Ative logs com variável de ambiente. Lembre-se: stdout é o canal do protocolo, stderr é para depuração.

Preciso instalar o Claude Code para usar MCP servers?

Para usar MCP servers com Claude Code, sim. Mas existem outros clientes MCP que você pode usar sem Claude Code, inclusive via linha de comando com o MCP Inspector ou programaticamente com o SDK. O ecossistema MCP está crescendo rapidamente.

Comece agora

Criar um MCP server Windows é o primeiro passo para transformar seu agente de IA em uma ferramenta verdadeiramente integrada ao seu ambiente de trabalho. Com Node.js e o SDK oficial, você pode construir desde pequenas automações até servidores completos que conectam seu ecossistema de desenvolvimento.

Quer levar a orquestração de agentes para o próximo nível? O Orquestra oferece suporte nativo a MCP servers, integração com Claude Code e Codex, e um canvas infinito para coordenar múltiplos agentes simultaneamente — tudo rodando nativamente no Windows.

Baixe o Orquestra para Windows 11 e comece a criar seus próprios MCP servers hoje mesmo. A versão gratuita inclui tudo que você precisa para explorar o protocolo e construir suas primeiras ferramentas.

Links relacionados:

Pronto para orquestrar seus agentes?

Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Grátis por 7 dias.

Começar teste grátis