MCP Document Server

You set up a dedicated MCP Server to deliver project documents to AI agents on demand, reducing token usage by loading context only when needed. This server centralizes document access, evaluates searches, and lets your team share a reliable, secure configuration for AI-assisted workflows.

How to use

You interact with the server through an MCP client to retrieve documents, list available documents, and search within documents. Use get_document to fetch a specific file, list_documents to see what is available, and search_in_document to find relevant terms inside a document. The server enforces safe file access and validates inputs to prevent security issues.

How to install

Prerequisites you need to prepare before starting include Python 3.10 or newer and a tool to install dependencies. A package manager is recommended for streamlined setup.

Steps to run locally using Poetry

# Clone the project repository
git clone <your-repo-url>
cd mcp_python

# Install dependencies (development dependencies included)
poetry install
poetry install

# Run the server
export MCP_DOCS_DIR=/path/to/your/documents
poetry run python -m mcp_server.main

Run with Docker locally

Build and run the container, mounting your documents directory into the container.

Steps to run with Docker

# Build the image
docker build -t mcp-document-server:latest .

# Run the container, mounting the documents directory
docker run -it --rm \
  -v $(PWD)/docs:/app/docs:ro \
  mcp-document-server:latest

Run with Docker Compose

docker-compose up -d

Claude Desktop integration

You can connect Claude Desktop to this MCP Server by providing a configuration that starts the server locally or via Docker. The examples below show two common approaches.

Local Claude Desktop configuration

{
  "mcpServers": {
    "document-server": {
      "command": "poetry",
      "args": ["run", "python", "-m", "mcp_server.main"],
      "env": {
        "MCP_DOCS_DIR": "/path/to/your/documents"
      }
    }
  }
}

Docker Claude Desktop configuration

{
  "mcpServers": {
    "document-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/documents:/app/docs:ro",
        "mcp-document-server:latest"
      ]
    }
  }
}

Testing and inspection

You can run the test suite to ensure all MCP features work as expected and use interactive inspection to test the server in a controlled environment.

Project structure and development notes

The server focuses on document tools and safe file handling, with a clean separation between server logic, document utilities, and logging. It supports a secure workflow with input validation and encoding safeguards.

Security and safety notes

To prevent path traversal and other attacks, document access is restricted to the designated documents directory and outside access is rejected. Large files are subject to size limits, and all inputs are validated before processing.

Notes on usage with environments

When running locally, define the documents directory through MCP_DOCS_DIR. When running in containers, mount the documents directory into the container and reference that path inside the server.

Available tools

get_document

Fetches the specified document from the configured documents directory and returns its contents to the MCP client.

list_documents

Lists all documents available in the configured documents directory, helping you quickly discover what you can request.

search_in_document

Searches for a keyword or phrase inside a given document and returns matching results to the client.