Como criar um servidor MCP local para o Claude: Arquivos, Comandos, Capturas de Tela e Controle de Aplicativos

O Claude fica muito mais útil quando deixa de ser apenas uma interface de chat.

Um servidor MCP local permite que o Claude interaja com sua máquina real: arquivos locais, comandos aprovados, capturas de tela e abertura de aplicativos. A parte importante não é o acesso bruto. É o acesso controlado.

Neste guia, vamos construir um servidor MCP local para o Claude que seja prático, restrito e seguro o suficiente para usar em fluxos de trabalho reais.

Uma observação rápida antes de construirmos qualquer coisa

Este artigo evita intencionalmente a versão irresponsável de "controle do computador".

Nós não vamos dar ao Claude acesso irrestrito ao shell, autoridade total sobre o sistema de arquivos ou permissão para modificar sua máquina sem proteções. A maneira mais rápida de construir um servidor MCP local ruim é expor uma ferramenta run_anything() gigante e chamar isso de inovação.

O padrão melhor é:

• diretórios na lista de permissões
• comandos na lista de permissões
• padrões seguros
• logs legíveis para humanos
• respostas explícitas
• separação clara entre ferramentas de somente leitura e de ação

Se o Claude pode fazer tudo, você construiu uma demonstração.

Se o Claude pode fazer as coisas certas com segurança, você construiu algo utilizável.

Por que vale a pena aprender essa arquitetura

O valor de um servidor MCP local não é a novidade. É a redução do atrito.

Sem uma camada de ferramentas local, seu fluxo de trabalho é assim:

1. Peça ao Claude o que fazer
2. Copie a resposta
3. Abra a pasta você mesmo
4. Execute o comando você mesmo
5. Tire a captura de tela você mesmo
6. Cole o resultado de volta no chat

Com um servidor MCP local, esse ciclo fica dramaticamente mais enxuto. O Claude pode inspecionar o contexto de que precisa, usar ferramentas com escopo restrito e retornar uma resposta fundamentada no estado real da sua máquina.

Isso é útil para:

• fluxos de trabalho de desenvolvimento
• inspeção de logs
• operações de conteúdo
• pipelines de pesquisa
• automação de desktop
• tarefas administrativas repetitivas

E como a camada de ferramentas é sua, você escolhe exatamente onde o modelo para.

Quer aprender sobre IA e se manter à frente na sua carreira?

Eu compartilho:

Mais de 1.000 prompts de IA

Ferramentas e automações de IA

Dicas de carreira e crescimento no LinkedIn

Recursos selecionados de tecnologia e produtividade

Inscreva-se aqui:

https://bytebuilders.beehiiv.com/subscribe

Siga-me para mais dicas de IA

👇

O design que estamos construindo

Vamos construir um servidor local com cinco ferramentas:

1. list_files — veja o que existe dentro de pastas aprovadas
2. read_file — abra arquivos de texto seguros
3. run_command — execute um pequeno conjunto de comandos locais aprovados
4. take_screenshot — salve uma captura de tela em um local conhecido
5. open_target — abra um aplicativo, arquivo, pasta ou URL

Esse escopo é deliberado.

É o suficiente para tornar o Claude significativamente útil em uma máquina local sem cair em automação insegura de propósito geral.

O modelo mental deve ser assim:

Claude → Cliente MCP → Servidor MCP local → Ferramentas restritas → Sistema operacional

O Claude nunca deve falar diretamente com seu sistema operacional. Seu servidor MCP é o plano de controle no meio.

A pilha de tecnologia

Para uma construção local, Python é uma escolha limpa porque o SDK oficial do MCP é maduro, a abstração FastMCP é concisa e Python continua sendo a linguagem mais fácil para trabalhar com sistema de arquivos, subprocessos e scripts de desktop 4 2.

Usaremos:

• Python 3.11+
• mcp[cli] para o runtime do servidor MCP
• mss para capturas de tela multiplataforma
• módulos da biblioteca padrão para acesso a arquivos, chamadas de subprocesso e manipulação do SO

Configure um novo projeto:

1mkdir local-mcp-server
2cd local-mcp-server
3uv init --python 3.11
4uv add "mcp[cli]>=1.0,<2.0" "mss>=9.0,<10.0"

O estilo FastMCP baseado em decoradores mantém a camada de protocolo fora do seu caminho para que você possa se concentrar na qualidade da ferramenta em vez da configuração 4 5.

Uma estrutura de projeto simples funciona bem:

1mkdir local-mcp-server
2cd local-mcp-server
3uv init --python 3.11
4uv add "mcp[cli]>=1.0,<2.0" "mss>=9.0,<10.0"

Você não precisa de uma arquitetura complexa para a v1. O que você precisa é de clareza.

O servidor propriamente dito

Crie o arquivo server.py e comece com uma implementação orientada por políticas.

1from __future__ import annotations
2
3import json
4import os
5import platform
6import shlex
7import subprocess
8from pathlib import Path
9from typing import Any
10
11import mss
12from mcp.server.fastmcp import FastMCP
13
14app = FastMCP("local-computer-control", json_response=True)
15
16HOME = Path.home()
17PROJECT_ROOT = Path(__file__).parent.resolve()
18CAPTURE_DIR = PROJECT_ROOT / "captures"
19CAPTURE_DIR.mkdir(exist_ok=True)
20
21ALLOWED_ROOTS = [
22    HOME / "Documents",
23    HOME / "Desktop",
24    PROJECT_ROOT,
25]
26
27ALLOWED_COMMANDS = {
28    "pwd",
29    "ls",
30    "git status",
31    "git diff --stat",
32    "python --version",
33    "node --version",
34    "npm --version",
35}
36
37READABLE_EXTENSIONS = {
38    ".txt",
39    ".md",
40    ".json",
41    ".py",
42    ".js",
43    ".ts",
44    ".tsx",
45    ".jsx",
46    ".yaml",
47    ".yml",
48    ".toml",
49    ".csv",
50    ".log",
51}
52
53def _resolve_path(raw_path: str) -> Path:
54    path = Path(raw_path).expanduser().resolve()
55    for root in ALLOWED_ROOTS:
56        root = root.resolve()
57        if path == root or root in path.parents:
58            return path
59    raise ValueError(f"Caminho não permitido: {path}")
60
61def _ensure_safe_command(command: str) -> str:
62    normalized = " ".join(shlex.split(command))
63    if normalized not in ALLOWED_COMMANDS:
64        raise ValueError(
65            "Comando não permitido. Adicione-o explicitamente a ALLOWED_COMMANDS se você realmente precisar dele."
66        )
67    return normalized
68
69@app.tool()
70def list_files(path: str = "~") -> dict[str, Any]:
71    """Lista arquivos e pastas dentro de um diretório aprovado."""
72    target = _resolve_path(path)
73    if not target.is_dir():
74        raise ValueError(f"Não é um diretório: {target}")
75
76    items = []
77    for child in sorted(target.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower())):
78        items.append(
79            {
80                "name": child.name,
81                "path": str(child),
82                "type": "directory" if child.is_dir() else "file",
83            }
84        )
85
86    return {
87        "path": str(target),
88        "count": len(items),
89        "items": items,
90    }
91
92@app.tool()
93def read_file(path: str, max_chars: int = 12000) -> dict[str, Any]:
94    """Lê um arquivo de texto seguro de um local aprovado."""
95    target = _resolve_path(path)
96    if not target.is_file():
97        raise ValueError(f"Não é um arquivo: {target}")
98    if target.suffix.lower() not in READABLE_EXTENSIONS:
99        raise ValueError(f"Tipo de arquivo não suportado: {target.suffix}")
100
101    content = target.read_text(encoding="utf-8", errors="replace")
102    truncated = len(content) > max_chars
103    content = content[:max_chars]
104
105    return {
106        "path": str(target),
107        "truncated": truncated,
108        "content": content,
109    }
110
111@app.tool()
112def run_command(command: str, cwd: str | None = None, timeout: int = 15) -> dict[str, Any]:
113    """Executa um comando local permitido."""
114    safe_command = _ensure_safe_command(command)
115    working_dir = _resolve_path(cwd) if cwd else PROJECT_ROOT
116
117    completed = subprocess.run(
118        safe_command,
119        shell=True,
120        cwd=str(working_dir),
121        capture_output=True,
122        text=True,
123        timeout=timeout,
124    )
125
126    return {
127        "command": safe_command,
128        "cwd": str(working_dir),
129        "returncode": completed.returncode,
130        "stdout": completed.stdout.strip(),
131        "stderr": completed.stderr.strip(),
132    }
133
134@app.tool()
135def take_screenshot(name: str = "latest") -> dict[str, Any]:
136    """Captura uma tela e salva localmente."""
137    output_path = CAPTURE_DIR / f"{name}.png"
138
139    with mss.mss() as sct:
140        sct.shot(output=str(output_path))
141
142    return {
143        "saved": True,
144        "path": str(output_path),
145    }
146
147@app.tool()
148def open_target(target: str) -> dict[str, Any]:
149    """Abre um arquivo, pasta, aplicativo ou URL aprovado usando o SO local."""
150    system = platform.system().lower()
151
152    if target.startswith("http://") or target.startswith("https://"):
153        resolved = target
154    else:
155        resolved = str(_resolve_path(target))
156
157    if system == "darwin":
158        subprocess.run(["open", resolved], check=True)
159    elif system == "windows":
160        os.startfile(resolved)  # type: ignore[attr-defined]
161    else:
162        subprocess.run(["xdg-open", resolved], check=True)
163
164    return {
165        "opened": True,
166        "target": resolved,
167    }
168
169if __name__ == "__main__":
170    app.run(transport="stdio")

Este é um servidor compacto, mas a parte importante não é sua extensão. A parte importante é a forma da interface:

• cada ferramenta tem um trabalho muito claro
• cada ferramenta retorna dados estruturados
• a execução de comandos é controlada
• o acesso a arquivos é enraizado
• as capturas de tela vão para uma pasta conhecida

Isso é exatamente o que você quer em um servidor MCP local.

Por que essas ferramentas são projetadas dessa forma

Conteúdo sênior sobre ferramentas de agente nunca deve parar em "aqui está o código". A forma da ferramenta é a verdadeira lição.

list_files

Esta ferramenta dá ao Claude uma superfície de descoberta segura. Ele deve ser capaz de responder perguntas como:

• O que há nesta pasta de projeto?
• Quais notas existem em Documentos?
• Já existe um arquivo de log que eu possa inspecionar?

Mas não deve se tornar um rastreador recursivo de disco inteiro.

read_file

Esta é muitas vezes a ferramenta local mais útil de todas. Uma grande porcentagem do trabalho real ainda está escondida em notas Markdown locais, logs, CSVs, documentos e arquivos de projeto.

O limite max_chars importa. Arquivos grandes são um problema de contexto e latência. Retornar o conteúdo inteiro de um arquivo de log gigante raramente é útil.

run_command

É aqui que a maioria das pessoas relaxa.

O padrão seguro não é "permitir acesso ao shell, depois torcer pelo melhor". O padrão seguro é "permitir um conjunto minúsculo de comandos exatos e revisáveis". É por isso que o exemplo usa uma lista de permissões estrita.

take_screenshot

Uma ferramenta de captura de tela é valiosa porque permite que o Claude participe de fluxos de trabalho de desktop. Mesmo que sua primeira versão apenas salve a imagem no disco, isso já é útil para relatórios, depuração de interface do usuário, captura de documentação e transferências estruturadas.

open_target

O controle de aplicativos não precisa começar com automação de GUI. Para muitos fluxos de trabalho, "abrir a pasta, arquivo ou URL certo" é suficiente.

Essa é uma v1 mais durável do que fingir que você precisa de automação completa do cursor no primeiro dia.

Conectando o servidor ao Claude

Servidores MCP locais são comumente executados sobre stdio, o que significa que o Claude inicia o processo localmente e se comunica com ele diretamente via stdin/stdout. Para um servidor de controle de computador local, esse é o padrão correto porque evita exposição de rede desnecessária 4 5.

O Claude Desktop suporta servidores MCP locais por meio de configuração, onde ele inicia o processo do servidor para você. Na prática, usar caminhos absolutos para o interpretador e o script é a configuração menos frágil porque os ambientes de aplicativos GUI locais são frequentemente mais restritos do que seu terminal 2.

Uma configuração mínima é assim:

1{
2  "mcpServers": {
3    "local-computer-control": {
4      "command": "/caminho/absoluto/para/python",
5      "args": [
6        "/caminho/absoluto/para/local-mcp-server/server.py"
7      ]
8    }
9  }
10}

Se você preferir uv, isso também funciona:

1{
2  "mcpServers": {
3    "local-computer-control": {
4      "command": "/caminho/absoluto/para/uv",
5      "args": [
6        "--directory",
7        "/caminho/absoluto/para/local-mcp-server",
8        "run",
9        "python",
10        "server.py"
11      ]
12    }
13  }
14}

Depois de salvar a configuração e reiniciar o Claude, as ferramentas do servidor devem aparecer na lista de ferramentas MCP locais. A configuração MCP local do Claude Desktop é construída exatamente em torno deste modelo: iniciar um processo local, conectar via stdio e expor as ferramentas ao modelo 2 3.

Prompts que são realmente úteis para teste

Assim que o servidor estiver conectado, não comece com orquestração complicada. Comece com verificações diretas e simples.

Experimente prompts como:

• "Liste os arquivos na minha pasta Desktop."
• "Leia ~/Documents/todo.md e resuma as três principais prioridades."
• "Execute git status na minha pasta de projeto local e explique o que mudou."
• "Tire uma captura de tela chamada workspace-check."
• "Abra o README do meu projeto."

Se esses fluxos simples funcionarem de forma consistente, você tem um servidor que vale a pena expandir.

Se não funcionarem, adicionar mais ferramentas só vai esconder os problemas reais.

Onde os servidores MCP locais se tornam genuinamente valiosos

O caso de uso óbvio é o desenvolvimento, mas isso é apenas uma via.

Fluxo de trabalho do desenvolvedor

O Claude pode:

• inspecionar uma pasta de repositório
• ler um arquivo de configuração
• executar git status
• capturar uma captura de tela de um estado de bug
• abrir o diretório do projeto

Isso já elimina muita alternância de contexto.

Fluxo de trabalho de pesquisa

O Claude pode:

• listar pastas de pesquisa
• abrir e resumir notas Markdown
• ler CSVs estruturados
• salvar capturas de tela de ferramentas ou painéis
• abrir arquivos de origem ou links de navegador

Fluxo de trabalho de conteúdo

O Claude pode:

• escanear uma pasta de rascunhos
• ler ideias de postagens existentes
• capturar uma captura de tela de uma referência de design
• abrir o arquivo de escrita ou URL correto
• executar um comando limitado que gera um artefato de compilação ou exportação de rascunho

Fluxo de trabalho de operações

O Claude pode:

• inspecionar logs de diretórios aprovados
• executar um comando de diagnóstico somente leitura
• abrir a pasta relevante ou link do painel
• salvar uma captura de tela como evidência

Este é o verdadeiro ponto da arquitetura: não "controle do computador" como uma façanha, mas compressão do fluxo de trabalho.

A camada de segurança é o produto

Esta é a seção que muitos artigos técnicos tratam com superficialidade.

A parte perigosa do MCP local não é o protocolo. É o design de permissões ruim.

Se você quer que este servidor seja utilizável além de uma demonstração, construa o modelo de segurança cedo.

Use listas de permissões de diretórios

O Claude só deve ser capaz de ver caminhos que você aprova explicitamente. É por isso que _resolve_path() é o núcleo das ferramentas de arquivo.

Use listas de permissões de comandos

Nunca exponha a execução arbitrária de shell em uma primeira versão. Comece com comandos exatos que você pode auditar linha por linha.

Separe ferramentas de leitura de ferramentas de ação

Ferramentas somente leitura devem ser o padrão. Ferramentas de ação devem ser introduzidas deliberadamente.

Registre tudo

Mesmo um log JSON simples de acréscimo torna a depuração e a confiança drasticamente melhores.

Adicione uma camada de confirmação para escritas

Se você adicionar posteriormente write_file, move_file ou delete_file, torne essas ferramentas que exigem um segundo token de confirmação ou mantenha-as desabilitadas por padrão.

Considere um modo de simulação

Para ferramentas de ação, o modo de simulação é subestimado. Ele permite que o Claude explique o que faria antes de fazê-lo.

Execute sob um usuário restrito quando possível

Se você leva a automação local a sério, não dê ao seu servidor MCP mais privilégios de SO do que ele precisa.

Uma regra prática útil:

• Nível 1: ferramentas somente leitura
• Nível 2: ações de baixo risco como abrir arquivo / abrir aplicativo
• Nível 3: ações de escrita confirmadas
• Nível 4: ações destrutivas que você provavelmente não deve expor casualmente

A maioria das pessoas nunca precisa do Nível 4.

O que melhorar após a v1

Uma primeira versão sólida ganha o direito de se tornar mais capaz.

Assim que o servidor básico estiver estável, as próximas atualizações sensatas são:

1. Arquivo de política centralizado

Mova suas regras para config/policy.json para que as alterações sejam declarativas.

Exemplo:

1{
2  "allowed_roots": [
3    "~/Documents",
4    "~/Desktop",
5    "./"
6  ],
7  "allowed_commands": [
8    "pwd",
9    "ls",
10    "git status",
11    "git diff --stat",
12    "python --version"
13  ]
14}

1. Registro estruturado

Registre chamadas de ferramentas, carimbos de data/hora, argumentos e resultados em logs/server.log ou um arquivo JSONL.

1. Execução de comando mais segura

Em vez de uma única ferramenta de comando genérica, divida os comandos em ferramentas mais restritas, como:

• git_status
• show_current_directory
• list_project_files

Isso torna a escolha da ferramenta mais fácil para o Claude e a segurança mais fácil para você.

1. Melhor manipulação de capturas de tela

Você pode evoluir de "salvar uma captura de tela no disco" para:

• capturas com carimbo de data/hora
• captura da janela ativa
• captura de região
• regras de retenção de arquivos

1. Adaptadores de automação específicos do SO

No macOS, você pode mais tarde adicionar AppleScript ou Shortcuts. No Windows, PowerShell ou Automação de Interface do Usuário. No Linux, lançadores e ferramentas de janela específicos do desktop.

Mas isso deve vir depois que o núcleo local básico for confiável.

Erros comuns que as pessoas cometem com servidores MCP locais

Os erros são previsíveis.

Erro 1: Muito poder, muito cedo

As pessoas adoram a ideia de controle total do computador. Elas odeiam depurá-lo. Comece menor.

Erro 2: Nomes de ferramentas vagos

Se os nomes de suas ferramentas são ambíguos, o Claude as usará mal. Seja explícito.

Ruim:

• system_action
• computer_control

Melhor:

• list_files
• read_file
• run_command
• take_screenshot
• open_target

Erro 3: Saídas não estruturadas

Um bloco de texto misturado é mais difícil para o Claude raciocinar do que um objeto JSON limpo.

Erro 4: Sem registro

Se uma ferramenta falha e você não consegue ver porquê, o sistema se torna um jogo de adivinhação.

Erro 5: Tratar o modelo como a camada de controle

O Claude é a camada de raciocínio. Seu servidor ainda deve ser a camada de aplicação.

Essa distinção é inegociável.

O que esta arquitetura faz melhor do que a automação simples

A automação de desktop tradicional geralmente é uma de duas coisas:

• scripts de GUI frágeis
• scripts isolados que exigem que um humano saiba exatamente quando executá-los

Um servidor MCP local muda isso porque o Claude pode decidir qual ferramenta usar com base na solicitação do usuário e no contexto disponível.

Isso significa que você não está apenas automatizando um comando. Você está construindo uma camada de capacidade local sobre a qual o modelo pode raciocinar.

É por isso que o MCP parece importante. Não é apenas mais um padrão de integração. É uma maneira mais limpa de expor o uso de ferramentas ao modelo sem codificar rigidamente todos os fluxos de trabalho possíveis na camada de aplicação.

Os limites que você deve respeitar

Mesmo um bom servidor MCP local tem limitações reais.

• A automação de desktop pode ser instável entre sistemas operacionais.
• Capturas de tela são úteis, mas não mágicas.
• Abrir aplicativos é fácil; a manipulação confiável da interface do usuário é mais difícil.
• O acesso genérico ao shell é perigoso.
• O inchaço do contexto é real se as saídas da ferramenta forem muito grandes.
• A aprovação humana ainda é valiosa para qualquer coisa consequente.

Em outras palavras: não confunda "o modelo pode tomar ações" com "o modelo deve agir sem supervisão".

O padrão mais valioso é o controle colaborativo, não a autonomia cega.