Installation

Folios is a Python package available on PyPI. It runs as a local MCP server — no cloud services, no network requests. Your documents stay on your machine.

Prerequisites

• uv — the MCP config uses uvx to run Folios, which handles Python automatically
• A folder of Markdown documents following the {id}_v{version}.md naming convention (see Document Format)

Documents path

Folios needs to know where your documents live. You can provide this via:

Method	Example
CLI flag	uvx folios --path /path/to/docs
Environment variable	export FOLIOS_PATH=/path/to/docs

The environment variable is useful when configuring Folios as an MCP server in a client, so you don't need to hardcode the path in each config file.

Optional settings

The only required setting is the documents path. You can optionally tune these:

Setting	CLI flag	Environment variable	Default	Description
Max file size	--max-file-size 20	MAX_DOCUMENT_SIZE=20	10 MB	Maximum document size in MB. Files exceeding this limit are skipped during catalog browsing (with a warning) and return an error when read directly. Increase if your documents are larger than 10 MB.

MCP client configuration

Folios is a stdio-based MCP server — your AI client launches it automatically as a subprocess. You don't need to run it separately. Just add the configuration below to your client's MCP settings.

Generic MCP configuration

Most MCP-compatible clients use a JSON configuration file. The standard config for Folios:

{
  "mcpServers": {
    "folios": {
      "command": "uvx",
      "args": ["folios", "--path", "/path/to/your/documents"]
    }
  }
}

Or using the environment variable:

{
  "mcpServers": {
    "folios": {
      "command": "uvx",
      "args": ["folios"],
      "env": {
        "FOLIOS_PATH": "/path/to/your/documents"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "folios": {
      "command": "uvx",
      "args": ["folios", "--path", "/path/to/your/documents"]
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

Folios is available as a Claude Code plugin. Install directly from the marketplace:

/plugin marketplace add alex-pradas/folios
/plugin install folios@alex-pradas-folios

Set the FOLIOS_PATH environment variable in your shell profile before using:

export FOLIOS_PATH=/path/to/your/documents

Alternatively, add Folios manually to your project's .mcp.json:

{
  "mcpServers": {
    "folios": {
      "command": "uvx",
      "args": ["folios", "--path", "/path/to/your/documents"]
    }
  }
}

Cursor

Click the button below to install Folios in Cursor with one click:

After installing, open .cursor/mcp.json and add the --path argument or set FOLIOS_PATH in your environment:

{
  "mcpServers": {
    "folios": {
      "command": "uvx",
      "args": ["folios", "--path", "/path/to/your/documents"]
    }
  }
}

VS Code (GitHub Copilot)

Add to your workspace .vscode/mcp.json or user settings.json:

{
  "mcpServers": {
    "folios": {
      "command": "uvx",
      "args": ["folios", "--path", "/path/to/your/documents"]
    }
  }
}

Windsurf

Add to your Windsurf MCP config at ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "folios": {
      "command": "uvx",
      "args": ["folios", "--path", "/path/to/your/documents"]
    }
  }
}

Cline

Folios is available in the Cline MCP Marketplace. Open the Extensions panel in Cline, search for "Folios", and install with one click.

For manual configuration, add to your Cline MCP settings:

{
  "mcpServers": {
    "folios": {
      "command": "uvx",
      "args": ["folios", "--path", "/path/to/your/documents"]
    }
  }
}

Codex (OpenAI)

Add to your Codex config at ~/.codex/config.toml:

[mcp_servers.folios]
command = "uvx"
args = ["folios", "--path", "/path/to/your/documents"]

Other MCP clients

Any client that supports the Model Context Protocol can use Folios. Use the generic MCP configuration above and consult your client's documentation for where to place it.

Verifying the installation

Once configured, your AI assistant should have access to six tools:

Tool	Description
browse_catalog	List documents with optional filters
get_document_content	Retrieve full document content
get_document_metadata	Get metadata and chapters
get_chapter_content	Retrieve a specific H2 section
diff_document_versions	Compare two document versions
list_revisions	List all versions of a document

Try asking your AI assistant: "What documents are available?" — it should call browse_catalog and return your document list.

Debugging

You don't need to run Folios manually — your MCP client handles that. But if you want to verify your documents parse correctly, you can run it standalone:

uvx folios --path /path/to/your/documents

This downloads and runs Folios in one command using uv. The server will start, scan your documents, and log what it finds. Press Ctrl+C to stop.