Test Files MCP

Generate test files directly from your AI coding assistant.

Need a 20 MB JPEG? A 100,000-row CSV? A corrupted PDF? Ask your MCP client and Test Files MCP creates it locally.

One-click install

Add to Cursor

Client	What happens when you click
Cursor	Opens Cursor and prompts you to add the MCP server
Claude Desktop	Downloads `test-files-mcp.mcpb` — double-click it to install

Claude Desktop has no URL deeplink for MCP JSON config. The .mcpb bundle is Anthropic's official one-click install format for local servers.

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "test-files": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Zulelee/test-files-mcp",
        "test-files-mcp"
      ]
    }
  }
}

Why this exists

Testing file uploads, parsers, validators, and storage limits usually means hunting for sample files or writing one-off scripts. Test Files MCP lets you describe what you need in plain language and get a real file on disk with useful metadata back.

Features

Dummy files — exact byte sizes (1 byte to GB-scale, within limits)
Images — JPEG, PNG, WEBP, BMP with dimensions, patterns, and approximate target sizes
PDFs — multi-page, blank or with fixture text, approximate target sizes
CSV — streamed generation up to 1M rows
JSON — valid or intentionally malformed fixtures
ZIP archives — empty, flat, or nested
WAV audio — tones or silence at configurable duration
Corrupted files — truncate, bad headers, garbage bytes, wrong extensions
Edge-case filenames — spaces, unicode, long names, hidden files
File inspection — size, MIME type, SHA256, image/audio metadata

Example prompts

Tell your MCP client things like:

Create a 25 MB JPEG

Generate a CSV with 500,000 rows

Create a corrupted PDF

Give me a 30-second WAV

Create an empty ZIP

Generate a weird filename for upload testing

Installation

With uvx (recommended)

From Git (replace Zulelee with your GitHub username or org):

uvx --from git+https://github.com/Zulelee/test-files-mcp test-files-mcp

After publishing to PyPI:

uvx test-files-mcp

From source

git clone https://github.com/Zulelee/test-files-mcp
cd test-files-mcp
uv sync
uv run test-files-mcp

Cursor setup

This repository follows the Agent Plugins standard. Plugin components live at the repo root:

.plugin/plugin.json      # Portable manifest
.cursor-plugin/plugin.json
.mcp.json               # MCP server (stdio via uv)
skills/                 # Agent skills
commands/               # Slash commands
agents/                 # Subagents
rules/                  # Project rules
hooks/hooks.json        # Lifecycle hooks
.lsp.json               # Python LSP config

Add to your Cursor MCP settings (.cursor/mcp.json or Cursor Settings → MCP):

{
  "mcpServers": {
    "test-files": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Zulelee/test-files-mcp",
        "test-files-mcp"
      ]
    }
  }
}

For local development:

{
  "mcpServers": {
    "test-files": {
      "command": "uv",
      "args": ["run", "test-files-mcp"],
      "cwd": "/path/to/test-files-mcp"
    }
  }
}

Claude Desktop setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "test-files": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Zulelee/test-files-mcp",
        "test-files-mcp"
      ]
    }
  }
}

Available MCP tools

Tool	Description
`create_dummy_file_tool`	Generic file with exact byte size
`create_image_tool`	JPEG, PNG, WEBP, BMP images
`create_pdf_tool`	Multi-page PDF fixtures
`create_csv_tool`	CSV with synthetic rows (streamed)
`create_json_tool`	Valid or malformed JSON
`create_archive_tool`	ZIP archives
`create_audio_tool`	WAV audio (tone or silence)
`create_corrupted_file_tool`	Corrupted copy of a file
`create_edge_case_filename_tool`	Files with tricky filenames
`inspect_file_tool`	Inspect file metadata

Configuration

Set environment variables to customize behavior:

Variable	Default	Description
`TEST_FILES_OUTPUT_DIR`	`./test-files-output/`	Default output directory
`TEST_FILES_MAX_FILE_SIZE_MB`	`250`	Maximum file size (MB)
`TEST_FILES_MAX_CSV_ROWS`	`1000000`	Maximum CSV rows
`TEST_FILES_MAX_PDF_PAGES`	`1000`	Maximum PDF pages
`TEST_FILES_MAX_IMAGE_DIMENSION`	`12000`	Max image width/height
`TEST_FILES_MAX_AUDIO_DURATION_SECONDS`	`600`	Max audio duration

Generated files are written to the output directory and returned as absolute paths.

Safety limits

This MCP intentionally generates large files. Requests exceeding configured limits return a clear error — values are never silently clamped.

Example error:

Requested file size is 500 MB, but the configured maximum is 250 MB.
Set TEST_FILES_MAX_FILE_SIZE_MB to increase the limit.

Development

git clone https://github.com/Zulelee/test-files-mcp
cd test-files-mcp
uv sync --group dev

Running tests

uv run pytest
uv run ruff check src tests

Rebuild Claude Desktop bundle

mcpb pack . dist/test-files-mcp.mcpb

Regenerate install badge URLs after changing MCP config:

uv run python scripts/generate-install-badges.py

MCP Inspector

uv run mcp dev src/test_files_mcp/server.py

Contributing

Contributions welcome! Please open an issue or pull request on GitHub.

License

MIT — see LICENSE.