Documentation

Model Context Protocol

MCP Server

Bring AI-powered file renaming, organization, and PDF splitting into Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. Tell the AI how you want your files named using plain English — it reads the actual document content and follows your instructions.

Features

Natural-language prompts — describe your naming rules in plain English (per-document-type rules, conditional logic, localization)
AI content analysis — OCR and NLP extract dates, vendors, amounts, document types, and reference numbers from file contents
PDF splitting — split PDFs by content/topic (AI), bookmarks, or page ranges
Organization strategies — auto-sort into folders by year, company, document type, or combinations
Dry-run mode — preview renames before committing changes

Quick Start

Add to Claude Code with a single command:

Terminal

$ claude mcp add renamed-to -- npx -y @renamed-to/mcp

Set your API key and you're ready to go:

$ export RENAMED_API_KEY="rt_..."

Using Claude Desktop, Cursor, or Windsurf? Add to your MCP config file:

claude_desktop_config.json

{
  "mcpServers": {
    "renamed-to": {
      "command": "npx",
      "args": ["-y", "@renamed-to/mcp"],
      "env": {
        "RENAMED_API_KEY": "rt_your_key_here"
      }
    }
  }
}

Authentication

Sign up for a renamed.to account
Go to Settings → API Keys and create a key
Set the environment variable in your MCP configuration

The server also accepts RENAMED_TOKEN as a fallback. Use the status tool to verify your connection.

Tools

rename

AI-powered file renaming with natural-language prompts

filePathsoutputDir?format?dryRun?

pdf_split

Split PDFs by content, bookmarks, or page ranges

filePathstrategy?outputDir?

watch

Monitor a directory for new files (delegates to CLI)

directoryoutputDir?

status

Check authentication and API connectivity

Rename

Sends files to the renamed.to API which reads the actual document content — OCR for scans, NLP for text — extracts metadata (dates, vendors, amounts, reference numbers), and generates filenames based on your instructions.

filePathsrequired

Absolute or relative paths to the files to rename.

outputDir

Directory to write renamed files to. Defaults to the source directory.

format

Natural-language prompt describing how filenames should be formatted. When not provided, the AI automatically selects the best naming pattern for each document.

dryRun

Preview the rename without writing any files.

Prompt examples

The format parameter accepts plain English instructions. The AI interprets them and applies them to each file based on its content:

Invoices: {date} - {vendor} - Invoice #{number} - ${amount}
Contracts: {vendor} - {type} - {date}
Receipts: {date} - {vendor} - Receipt

You can specify per-document-type rules, conditional logic, localization, and more:

Department prefixes — "Add HR_ prefix for employment documents, FIN_ for financial records"
Localization — "Use German date format DD.MM.YYYY, translate document types to German"
Conditional logic — "If invoice amount > $1000, add LARGE_ prefix"
Industry formats — "Include matter number for legal documents, client code for accounting"

PDF Split

The AI reads the full document, identifies logical sections and topic boundaries, and creates individually named PDFs for each.

filePathrequired

Path to the PDF file to split.

strategy

Split strategy: ai (analyzes content and splits by topic), bookmarks (splits at PDF bookmark boundaries), or pages (splits by page ranges). Defaults to ai.

outputDir

Directory to write the split PDF files to. Defaults to the source directory.

Tool Annotations

Tool	Read-Only	Destructive	Idempotent
`rename`	No	Yes (renames files in place)	No
`pdf_split`	No	No (creates new files)	Yes
`watch`	Yes (informational)	No	Yes
`status`	Yes	No	Yes

Examples

“Rename all the PDFs in my Downloads folder based on their content”

The AI reads each file — even scanned images via OCR — extracts dates, vendors, document types, and generates descriptive names.

“Rename these files. For invoices use '{date} - {vendor} - Invoice #{number}', for contracts use '{vendor} - {type} - {date}', and add a LARGE_ prefix if the amount is over $1000”

Applies different naming rules per document type with conditional logic, all from a single plain-English prompt.

“Split this 50-page annual report into separate documents by topic”

Analyzes content boundaries and creates individually named PDFs for each logical section — no bookmarks required.

“Do a dry run rename of these invoices using German date format DD.MM.YYYY and translate document types to German”

Shows what the new filenames would be without moving any files. The AI handles localization and translation in the naming.

Configuration

Claude Code

$ claude mcp add renamed-to -- npx -y @renamed-to/mcp

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor

Add to your MCP configuration (Settings → MCP Servers) using the same JSON format.

Windsurf

Add to your MCP configuration using the same JSON format.

Error Handling

Error	Cause	Resolution
Not configured	`RENAMED_API_KEY` not set	Add your API key to the environment (get one here)
Authentication failed	Invalid or expired API key	Generate a new key at Settings → API Keys
Insufficient credits	Account credits depleted	Top up at Settings → Billing
Rate limit exceeded	Too many requests	Wait and retry
Network error	Cannot reach the API	Check your internet connection
File not found	Invalid file path	Verify the path exists and is accessible

Security

API key is read from environment variables only — never hardcoded or logged
File contents are sent to the renamed.to API for analysis — be aware of this when processing sensitive documents
Runs locally via stdio transport — no network ports are opened on your machine
No data stored — the server is stateless between requests

Requirements

Node.js 20 or later. The server is installed automatically via npx — no manual installation needed.

Resources

GitHub Repository npm Package API Documentation CLI Documentation