This server allows AI clients to securely manage text files and directories within a configured local workspace. Here's what you can do:
List files (list_files): Browse the contents (files and subdirectories) of any folder within the workspace.
Read files (download_file): Read and retrieve the UTF-8 text content of any file.
Write/Upload files (upload_file): Create or overwrite text files, with automatic creation of parent directories if needed.
Get file metadata (get_file_info): Retrieve size, creation date, modification date, and type for any file or directory.
Delete files/directories (delete_file): Remove a file or empty directory from the workspace.
Create directories (create_directory): Recursively create new directories within the workspace.
Move/Rename files (move_file): Move or rename files and directories using relative source and destination paths.
Security: All operations are restricted to the configured workspace path, with strict path validation to prevent directory traversal attacks.
Permite ao n8n gerenciar arquivos e pastas em um diretório local seguro, utilizando ferramentas para listar, ler, criar, atualizar, mover e excluir arquivos.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Local File Manager list files in the workspace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Este é um projeto de estudo desenvolvido para aprofundamento no Model Context Protocol (MCP). Ele implementa um servidor MCP que permite a clientes de IA (como o Claude Desktop ou outras ferramentas habilitadas com MCP) gerenciar e manipular arquivos de texto em um diretório local seguro configurado via variáveis de ambiente.
O projeto foi construído utilizando Node.js, TypeScript e o SDK oficial da Anthropic (@modelcontextprotocol/sdk).
Runtime: Node.js (v18+)
Linguagem: TypeScript (transpilado para ES Modules)
MCP SDK: @modelcontextprotocol/sdk (transporte via Stdio)
Validação de Dados: zod
Gerenciamento de Ambiente: dotenv
Execução em Desenvolvimento: tsx
Related MCP server: ABSD DevOps MCP Server
Execute o comando abaixo na pasta raiz do projeto:
npm installCopie o arquivo .env.example para .env ou crie-o manualmente:
cp .env.example .envEdite o arquivo .env e configure o caminho absoluto do diretório local que o servidor deve gerenciar:
LOCAL_WORKSPACE_PATH=C:\caminho\completo\para\sua\pasta\workspace(Nota: O servidor validará a existência deste diretório ao iniciar e lançará um erro se ele não for encontrado).
Para gerar o código JavaScript transpilado pronto para produção:
npm run buildO output será gerado na pasta /dist.
O servidor pode ser executado em dois modos de transporte: Stdio (padrão) ou SSE (Server-Sent Events).
Ideal para integração local com clientes como o Claude Desktop.
npm start
# ou em desenvolvimento
npm run devIdeal para integração com plataformas como n8n, OpenClaw, ou outros clientes de rede.
Você pode ativar este modo definindo TRANSPORT=sse no arquivo .env, ou passando o argumento --sse na inicialização:
npm start -- --sse
# ou em desenvolvimento
npm run dev -- --sseVocê também pode configurar uma porta customizada usando a variável de ambiente PORT ou passando o argumento --port <numero>:
npm start -- --sse --port 4000Quando executado em modo SSE, o servidor subirá uma aplicação Express com os seguintes endpoints:
GET /sse (para iniciar o fluxo de stream de Server-Sent Events)
POST /messages (para o envio de comandos JSON-RPC do cliente)
Para garantir a integridade dos dados e do sistema host, o servidor MCP implementa um validador de caminho estrito chamado safeResolvePath. Qualquer tentativa de um modelo de IA acessar arquivos fora do diretório especificado em LOCAL_WORKSPACE_PATH (utilizando caminhos relativos como ../../ ou absolutos como C:/Windows) será imediatamente negada pelo servidor com uma mensagem de erro controlada.
O servidor disponibiliza 7 ferramentas para os clientes de IA realizarem o gerenciamento de arquivos:
list_files: Lista arquivos e subdiretórios a partir de um relativePath opcional (vazio para a raiz).
download_file: Lê e retorna o conteúdo em UTF-8 de um arquivo de texto simples especificado pelo relativePath.
upload_file: Grava ou sobrescreve o conteúdo UTF-8 de um arquivo de texto. Cria subpastas pai automaticamente se não existirem.
get_file_info: Retorna os metadados detalhados (tamanho, data de criação, data de modificação e status de tipo) de um arquivo ou diretório.
delete_file: Remove de forma segura um arquivo ou um diretório vazio especificado pelo relativePath.
create_directory: Cria um novo diretório de forma recursiva dentro da pasta de trabalho.
move_file: Renomeia ou move arquivos e diretórios dentro do workspace usando caminhos relativos de origem (sourcePath) e destino (destinationPath).
O MCP Inspector é uma ferramenta oficial de testes interativos que simula o comportamento de um cliente MCP via Stdio:
Garanta que o projeto esteja compilado (npm run build).
Rode o Inspector no terminal do projeto:
npx @modelcontextprotocol/inspector node dist/index.jsAcesse o link gerado no seu terminal (por padrão http://localhost:6274) no navegador para testar interativamente cada uma das ferramentas.
Para utilizar este servidor MCP no aplicativo oficial do Claude Desktop, edite o arquivo de configuração claude_desktop_config.json:
Caminho no Windows: %APPDATA%\Claude\claude_desktop_config.json
Caminho no macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Adicione a seguinte entrada dentro de mcpServers:
{
"mcpServers": {
"local-file-manager": {
"command": "node",
"args": [
"C:\\Users\\seu-usuario\\Documents\\Pessoal\\my-first-mpc-server\\dist\\index.js"
],
"env": {
"LOCAL_WORKSPACE_PATH": "C:\\Users\\seu-usuario\\Documents\\Pessoal\\my-first-mpc-server\\workspace"
}
}
}
}(Lembre-se de ajustar os caminhos absoluto do arquivo index.js e do diretório local para os caminhos corretos da sua máquina).
Cria um novo diretório dentro da pasta gerenciada.
| Name | Required | Description | Default |
|---|---|---|---|
| relativePath | Yes | Caminho relativo do novo diretório |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond the core action. No mention of permissions, error conditions, or side effects (e.g., whether intermediate directories are created).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence (6 words) that efficiently conveys the tool's purpose. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is adequate but does not address preconditions like parent directory existence or whether the path is relative to a specific root.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter 'relativePath' has a basic description in the schema. The tool description adds no additional semantic meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new directory inside a managed folder, with a specific verb and resource. It is distinct from sibling tools which operate on files (delete, download, etc.)
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description simply states what it does without contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exclui um arquivo ou uma pasta vazia do diretório gerenciado.
| Name | Required | Description | Default |
|---|---|---|---|
| relativePath | Yes | Caminho relativo do arquivo ou pasta |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions that only empty folders are deleted, which is a key behavior. However, it does not disclose whether deletion is permanent or reversible, nor any permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. Every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and no output schema, the description is mostly adequate. However, it lacks information about success/error states, permanence, and potential side effects. Sibling tools are not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description adds no additional meaning beyond what the schema already provides. The parameter 'relativePath' is already described as 'Caminho relativo do arquivo ou pasta' in both the schema and the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('delete') and the target ('file or empty folder'), providing a specific verb and resource. It distinguishes from sibling tools like move_file or upload_file by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., move_file could archive). No prerequisites mentioned, such as the file/folder existing or the folder being empty. The description does not specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lê e retorna o conteúdo de um arquivo de texto dentro do diretório gerenciado.
| Name | Required | Description | Default |
|---|---|---|---|
| relativePath | Yes | Caminho relativo do arquivo |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden; it mentions reading text files but omits details like handling of binary files, permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded, but could benefit from slight elaboration on return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description fails to explain return format, encoding, or size limits; incomplete for a robust tool definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds no extra meaning beyond the schema's parameter description 'relative path of the file'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads and returns the content of a text file within the managed directory, differentiating it from sibling tools like delete_file or list_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage on the managed directory, but no explicit when-to-use or when-not-to-use guidance, and no alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retorna metadados detalhados de um arquivo ou diretório.
| Name | Required | Description | Default |
|---|---|---|---|
| relativePath | Yes | Caminho relativo do arquivo ou diretório |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states it returns metadata, but does not specify whether it is read-only, error handling, or any side effects. It lacks transparent behavioral traits beyond the basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, 10 words, that efficiently conveys the tool's purpose. It is front-loaded and contains no unnecessary words, earning a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is minimally adequate. However, it does not elaborate on what metadata is returned (e.g., size, date), nor does it address error conditions, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'relativePath', and the description does not add meaning beyond the schema's field description. Baseline 3 is appropriate as the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'returns' and the resource 'detailed metadata of a file or directory', which distinguishes it from sibling tools like download_file (file content) or list_files (list files). The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., list_files, download_file). There is no explicit context for when it is appropriate or not, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista o conteúdo de uma pasta do diretório gerenciado (arquivos e subpastas).
| Name | Required | Description | Default |
|---|---|---|---|
| relativePath | No | Caminho relativo da subpasta (opcional, vazio para a raiz) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It states the action is listing, implying a read-only operation, but does not explicitly confirm non-destructiveness or mention any side effects, rate limits, or permissions. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key action. It is appropriately sized for a simple tool, though it could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema), the description provides enough context to understand its purpose and usage. It is complete for its complexity level, though it omits details like return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the single parameter with a description (100% coverage). The tool description adds no further detail about the parameter beyond what the schema provides, so baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists the contents (files and subfolders) of a folder in the managed directory, providing a specific verb and resource. It distinguishes well from sibling tools which perform different operations like creating, deleting, or moving files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives, such as get_file_info for a single file. The context of sibling tools implies distinct purposes, but no direct exclusions or when-not-to-use advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move ou renomeia um arquivo ou diretório dentro da pasta gerenciada.
| Name | Required | Description | Default |
|---|---|---|---|
| sourcePath | Yes | Caminho relativo de origem | |
| destinationPath | Yes | Caminho relativo de destino |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavioral traits. It does not mention whether overwrites occur, permission requirements, what happens if sourcePath is missing, or if the operation is atomic. The description is too brief to inform the agent of important behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence in Portuguese, front-loading the action. It is not verbose but lacks structure (e.g., separate statements for move vs rename). Still, it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and lack of output schema, the description should explain what the tool returns or changes. It does not clarify whether moving and renaming are the same operation, nor does it account for error scenarios. Agent may not understand the full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described (sourcePath and destinationPath). The description adds no extra meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves or renames a file or directory within the managed folder. It uses a specific verb and resource and distinguishes itself from sibling tools like create_directory, delete_file, and upload_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., when to move vs copy or delete). No context about prerequisites, use cases, or exclusions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Grava ou sobrescreve um arquivo de texto no diretório gerenciado.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Conteúdo em texto simples a ser gravado | |
| relativePath | Yes | Caminho relativo do arquivo |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the overwrite behavior, which adds some transparency. However, without annotations, it fails to disclose potential failure modes, file size limits, or whether it handles non-text content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise and front-loaded. Every word is necessary and efficiently communicates the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple two-parameter tool with no output schema. Could be improved by specifying file size limits, encoding, or potential error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal extra meaning beyond the schema. It provides context (text file, managed directory) but no further details on parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (saves/overwrites), resource (text file), and location (managed directory). It effectively differentiates from siblings like delete_file or list_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_directory or move_file. It does not indicate that it is for text files only or that it overwrites existing files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0create_directorydelete_filedownload_fileget_file_infolist_filesmove_fileupload_fileScored across 7 tools
Each tool serves a distinct file operation (create, delete, read, info, list, move, write) with no overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case, making them predictable and easy to understand.
Seven tools provide a balanced set of file management operations without being too few or too many for the domain.
Covers core CRUD and listing, but lacks a copy operation and advanced features like search; minor gaps for typical file management.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
File uploads for AI agents. Upload, list, and manage files. No signup required.
Securely search and manage workspace context files for AI agents and teams.