Claude Code · 2026-07-12

Criando Ferramentas MCP para Claude Code no Windows

Guia completo para criar ferramentas MCP (Model Context Protocol) para Claude Code no Windows. Aprenda a estender as capacidades do agente com ferramentas personalizadas em Node.js, Python e PowerShell.

O Claude Code já é poderoso por si só, mas suas capacidades podem ser expandidas quase infinitamente através do MCP (Model Context Protocol). O MCP permite criar ferramentas personalizadas para Claude Code que acessam bancos de dados, APIs externas, sistemas de arquivos e qualquer outro recurso que você precise — tudo invocável por comandos em linguagem natural. Este guia ensina a criar suas próprias ferramentas MCP no Windows.

O que é MCP e como funciona

MCP (Model Context Protocol) é um protocolo aberto que permite que modelos de linguagem como Claude se comuniquem com ferramentas externas de forma padronizada. Pense no MCP como um "USB-C" para IAs: um conector universal que permite conectar qualquer ferramenta a qualquer modelo compatível.

O fluxo de funcionamento é simples:

Você cria um servidor MCP que expõe uma ou mais ferramentas
O Claude Code se conecta ao servidor (local ou remoto)
Quando o Claude Code entende que uma ferramenta pode ajudar, ele a invoca automaticamente
O resultado da ferramenta é inserido no contexto do Claude Code, que o utiliza para gerar a resposta

Isso significa que você pode ensinar o Claude Code a consultar seu banco de dados PostgreSQL, buscar issues no GitHub, ler planilhas Excel, ou qualquer outra tarefa — sem precisar de integrações complexas.

Servidor MCP simples com Node.js

Vamos criar um servidor MCP básico em Node.js. O servidor expõe uma ferramenta de calculadora que o Claude Code pode usar para fazer cálculos precisos.

Estrutura do projeto

# mcp-calculator/ # package.json # server.js

package.json

{ "name": "mcp-calculator", "version": "1.0.0", "type": "module", "dependencies": { "@modelcontextprotocol/sdk": "^1.0.0" } }

server.js — servidor MCP com ferramentas

import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; const server = new Server({ name: 'mcp-calculator', version: '1.0.0', }, { capabilities: { tools: {} }, }); // Define a ferramenta de calculadora server.setRequestHandler('tools/list', async () => ({ tools: [{ name: 'calculate', description: 'Executa cálculos matemáticos precisos', inputSchema: { type: 'object', properties: { expression: { type: 'string', description: 'Expressão matemática (ex: 2 + 2 * 3)', }, }, required: ['expression'], }, }], }));

server.setRequestHandler('tools/call', async (request) => { if (request.params.name === 'calculate') { const { expression } = request.params.arguments; try { const result = Function(`"use strict"; return (`${expression}`)`)(); return { content: [{ type: 'text', text: `Resultado: `${result}` }], }; } catch (error) { return { content: [{ type: 'text', text: `Erro: `${error.message}` }], isError: true, }; } } }); // Inicia o servidor via stdio const transport = new StdioServerTransport(); await server.connect(transport);

Este servidor MCP expõe uma ferramenta calculate que o Claude Code pode invocar sempre que precisar fazer cálculos precisos. O servidor roda via stdio (entrada/saída padrão), que é a forma mais comum de integração no terminal.

Ferramenta de consulta a banco de dados

Uma das ferramentas MCP mais úteis para desenvolvimento é a consulta a banco de dados. Vamos criar uma ferramenta que permite ao Claude Code executar queries SQL.

import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import pg from 'pg'; const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 1, // uma conexão por vez para segurança }); const server = new Server({ name: 'mcp-database', version: '1.0.0', }, { capabilities: { tools: {} }, }); server.setRequestHandler('tools/list', async () => ({ tools: [{ name: 'query_database', description: 'Executa consulta SQL no banco de dados', inputSchema: { type: 'object', properties: { sql: { type: 'string', description: 'Consulta SQL SELECT' }, params: { type: 'array', items: { type: 'string' }, description: 'Parâmetros para a query', }, }, required: ['sql'], }, }], })); server.setRequestHandler('tools/call', async (request) => { if (request.params.name === 'query_database') { const { sql, params = [] } = request.params.arguments; // Segurança: apenas SELECT if (!sql.trim().toUpperCase().startsWith('SELECT')) { return { content: [{ type: 'text', text: 'Apenas queries SELECT são permitidas' }], isError: true, }; } try { const result = await pool.query(sql, params); return { content: [{ type: 'text', text: JSON.stringify(result.rows.slice(0, 50), null, 2), }], }; } catch (error) { return { content: [{ type: 'text', text: `Erro SQL: ${error.message}` }], isError: true, }; } } });

Note as proteções de segurança: apenas queries SELECT, máximo de 50 linhas retornadas, parâmetros tipados para prevenir injection. Essas proteções são essenciais ao expor ferramentas para agentes de IA.

Ferramenta de integração com API externa

Outro caso de uso comum: permitir que o Claude Code interaja com a API do GitHub para buscar issues, PRs e repositórios.

server.setRequestHandler('tools/list', async () => ({ tools: [ { name: 'github_get_issues', description: 'Lista issues abertas de um repositório GitHub', inputSchema: { type: 'object', properties: { repo: { type: 'string', description: 'formato: owner/repo' }, limit: { type: 'number', description: 'máx de issues (padrão 10)' }, }, required: ['repo'], }, }, { name: 'github_search_code', description: 'Busca código em repositórios GitHub', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'termo de busca' }, }, required: ['query'], }, }, ], })); server.setRequestHandler('tools/call', async (request) => { const GITHUB_TOKEN = process.env.GITHUB_TOKEN; if (request.params.name === 'github_get_issues') { const { repo, limit = 10 } = request.params.arguments; const url = `https://api.github.com/repos/${repo}/issues?state=open&per_page=${limit}`; const res = await fetch(url, { headers: { Authorization: `Bearer ${GITHUB_TOKEN}` }, }); const issues = await res.json(); return { content: [{ type: 'text', text: issues.map(i => `#${i.number}: ${i.title}`).join('\n'), }], }; } });

Com essa ferramenta, o Claude Code pode buscar issues do GitHub, analisar o código relevante e propor correções — tudo em um fluxo contínuo, sem você precisar sair do terminal.

Conectando o servidor MCP ao Claude Code

Para que o Claude Code use suas ferramentas MCP, você precisa configurar o servidor no arquivo de configuração do Claude Code.

Configuração no CLAUDE.md global

# No arquivo ~/.claude/settings.json (Windows: %APPDATA%\Claude\settings.json) { "mcpServers": { "calculator": { "command": "node", "args": ["C:/tools/mcp-calculator/server.js"] }, "database": { "command": "node", "args": ["C:/tools/mcp-database/server.js"], "env": { "DATABASE_URL": "postgresql://localhost:5432/meudb" } }, "github": { "command": "node", "args": ["C:/tools/mcp-github/server.js"], "env": { "GITHUB_TOKEN": "ghp_seu_token_aqui" } } } }

Após configurar, inicie o Claude Code e ele carregará automaticamente todas as ferramentas MCP. O agente decide quando invocar cada ferramenta com base no contexto da conversa.

Gerenciando MCPs no Orquestra

Gerenciar múltiplos servidores MCP manualmente pode ser complexo. O Orquestra simplifica o gerenciamento de MCPs com uma interface centralizada no canvas:

Painel de MCPs: Ative, desative e configure servidores MCP sem editar arquivos JSON manualmente
Visibilidade por agente: Decida quais ferramentas MCP cada agente (Claude Code, Codex, OpenCode) pode acessar
Logs centralizados: Veja todas as chamadas MCP em tempo real, com parâmetros e resultados
Templates: Crie templates de MCP que podem ser reutilizados entre projetos

O MCP é uma das formas mais poderosas de estender o Claude Code. Combinado com a orquestração de agentes de IA, você cria um ecossistema onde cada agente tem acesso a ferramentas especializadas para suas tarefas.

Perguntas frequentes

O que é MCP no Claude Code?

MCP (Model Context Protocol) é um protocolo que permite estender as capacidades do Claude Code com ferramentas personalizadas. Com MCP, você pode adicionar funcionalidades como consultas a bancos de dados, integração com APIs externas, manipulação de arquivos e muito mais.

Preciso saber programar para criar ferramentas MCP?

Sim. Criar ferramentas MCP exige conhecimento básico de programação (Node.js, Python ou PowerShell). O servidor MCP é um programa que expõe ferramentas via protocolo padronizado. Mas uma vez criada, a ferramenta pode ser usada por qualquer pessoa via comandos em linguagem natural.

Ferramentas MCP funcionam no Windows?

Sim. O MCP é independente de plataforma. No Windows, você pode criar servidores MCP em Node.js (rodando no CMD ou PowerShell) ou Python (rodando no WSL). O Orquestra gerencia servidores MCP centralizadamente no canvas.

Quais ferramentas MCP são mais úteis para desenvolvimento?

As mais comuns são: consulta a banco de dados, integração com APIs externas (GitHub, Jira, Slack), manipulação de arquivos em formatos específicos (CSV, PDF, Excel), e automação de deploy.

Ferramentas MCP consomem tokens do Claude Code?

O resultado da ferramenta MCP é inserido no contexto do Claude Code, então sim, consome tokens. Por isso é importante que as ferramentas retornem apenas informações relevantes e concisas.

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