Skip to main content
Glama
hackerpl

FTP Doc Reader MCP Server

by hackerpl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

FTP Doc Reader MCP Server

中文文档

An MCP (Model Context Protocol) server that recursively searches .doc and .docx files in a specified directory on a remote FTP/FTPS server, matches document content by keyword, and returns relevant files with context snippets.

Features

  • Recursive directory scanning: Automatically scans all Word documents in FTP directories and subdirectories (max depth 10, max 200 files)

  • Content keyword matching: Case-insensitive full-text search, returns context snippets (100 characters before and after each match)

  • Supports .doc and .docx: Handles both legacy binary format and modern XML format

  • FTP/FTPS dual protocol: Supports plain FTP and TLS-encrypted FTPS

  • Local file caching: Size-based cache invalidation strategy to avoid redundant downloads

  • Auto retry: Transient network errors are automatically retried 3 times (2-second intervals)

  • Deploy via uvx: No manual dependency management required

Related MCP server: Word Document Reader MCP Server

Installation

Via uvx (Recommended)

uvx ftp-doc-reader

From source

git clone https://github.com/hackerpl/doc-mcp-server.git
cd doc-mcp-server
pip install -e .

MCP Configuration

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "ftp-doc-reader": {
      "command": "uvx",
      "args": ["ftp-doc-reader"],
      "env": {
        "FTP_HOST": "ftp.example.com",
        "FTP_USERNAME": "your_username",
        "FTP_PASSWORD": "your_password",
        "FTP_PROTOCOL": "FTP",
        "FTP_PORT": "21",
        "CACHE_DIR": ".cache"
      }
    }
  }
}

Kiro

Edit .kiro/settings/mcp.json:

{
  "mcpServers": {
    "ftp-doc-reader": {
      "command": "uvx",
      "args": ["ftp-doc-reader"],
      "env": {
        "FTP_HOST": "ftp.example.com",
        "FTP_USERNAME": "your_username",
        "FTP_PASSWORD": "your_password"
      },
      "disabled": false,
      "autoApprove": ["search_docs"]
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ftp-doc-reader": {
      "command": "uvx",
      "args": ["ftp-doc-reader"],
      "env": {
        "FTP_HOST": "ftp.example.com",
        "FTP_USERNAME": "your_username",
        "FTP_PASSWORD": "your_password"
      }
    }
  }
}

From GitHub source (development)

{
  "mcpServers": {
    "ftp-doc-reader": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/hackerpl/doc-mcp-server.git", "ftp-doc-reader"],
      "env": {
        "FTP_HOST": "ftp.example.com",
        "FTP_USERNAME": "your_username",
        "FTP_PASSWORD": "your_password"
      }
    }
  }
}

Environment Variables

Variable

Required

Default

Description

FTP_HOST

✅

—

FTP server hostname or IP

FTP_USERNAME

✅

—

FTP login username

FTP_PASSWORD

✅

—

FTP login password

FTP_PORT

❌

21

FTP server port

FTP_PROTOCOL

❌

FTP

Connection protocol: FTP or FTPS

CACHE_DIR

❌

.cache

Local cache directory path

Environment variables can be set via the env field in MCP configuration, or by placing a .env file in the project directory.

MCP Tool

search_docs

Search Word document content in a remote FTP directory.

Parameters:

Parameter

Type

Description

query

string (1-500 chars)

Search keyword or phrase

directory_path

string (1-1024 chars)

Remote FTP directory path

Returns:

A list of matching results (sorted by match count descending), each containing:

  • file_path — Full remote path of the file

  • file_name — File name

  • snippets — List of matched context snippets (max 5 per file)

Usage example:

Search for documents containing "installation guide" in the /products/docs directory on the FTP server

The AI assistant will call:

{
  "tool": "search_docs",
  "arguments": {
    "query": "installation guide",
    "directory_path": "/products/docs"
  }
}

Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov

# Start server directly (requires .env file)
python -m ftp_doc_reader

Tech Stack

  • Python 3.10+

  • MCP Python SDK (FastMCP)

  • python-docx (.docx parsing)

  • olefile (.doc parsing)

  • python-dotenv (environment variable management)

License

MIT

Available Tools

1 tool
search_docsB

Search .doc/.docx files in a remote FTP directory for content matching the query.

Args: query: Search keyword or phrase for content matching (1-500 characters). directory_path: Remote FTP directory path to search in (1-1024 characters).

Returns: List of search results sorted by snippet count (descending), or an error message string on failure.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
directory_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses return format (sorted list by snippet count) and error message on failure. With no annotations, it covers basic behavior but omits details like 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Reasonably concise with structured Args/Returns sections. No superfluous content; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simple parameters, no siblings, and no annotations, the description adequately covers purpose, parameters, and output. Could mention search behavior (case-sensitivity, regex) but sufficient for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds meaningful constraints (character length limits) and clarifies purpose for each parameter, compensating for 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches .doc/.docx files in an FTP directory for content matching the query. It specifies the resource and action, but lacks differentiation from potential siblings (none present).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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. It simply describes what it does without context on scenarios or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.1
    • First observedsearch_docs
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools.

Naming Consistency5/5

With a single tool, naming consistency is trivially maintained.

Tool Count2/5

The server has only one tool, which feels insufficient for a 'Doc Reader' server—missing basic operations like listing or downloading documents.

Completeness2/5

The tool only supports searching; there are no tools for listing, reading, or managing documents, leaving significant gaps for document reading tasks.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers