@codebyai/file-mcp

CodeByAI File MCP

@codebyai/file-mcp acts as a Model-Context-Protocol (MCP) server, giving your AI coding assistant access to powerful file operations and frontend development tools.

Key features

• XLSX Operations: Complete Excel file manipulation with multi-sheet support - read, write, edit, filter, and summarize XLSX files
• File Understanding: Analyze PDF, MP4, and MP3 files using Google Gemini AI

Disclaimers

@codebyai/file-mcp communicates with the CodeByAI web service (https://codebyai.com) to process design files and AI analysis requests. Design files and content you submit will be sent to this service. Avoid submitting sensitive or confidential information.

Requirements

• Node.js v18.0.0 or newer
• npm
• A modern web browser (for interactive tools)

Getting started

Before installing, generate or obtain an API_KEY. This key starts with "sk-" and is referred to as CODEBYAI_API_KEY. Replace {CODEBYAI_API_KEY} in the installation command with your actual key.

Add the following config to your MCP client:

{
  "mcpServers": {
    "file": {
      "command": "npx",
      "args": ["-y", "@codebyai/file-mcp@latest"],
      "env": {
        "CODEBYAI_API_KEY" : "{CODEBYAI_API_KEY}"
      }
    }
  }
}

[!NOTE] Using @codebyai/file-mcp@latest ensures that your MCP client will always use the latest version of the File MCP server.

MCP Client configuration

[!IMPORTANT] All client configurations below require you to replace {CODEBYAI_API_KEY} with your actual API key obtained from https://codebyai.com/console/api-keys.

Claude Code

Use the Claude Code CLI to add the File MCP server (guide):

claude mcp add file npx @codebyai/file-mcp@latest --env CODEBYAI_API_KEY={CODEBYAI_API_KEY}

Alternatively, manually edit your Claude Code MCP configuration file and add the environment variable.

Cline

Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above (including the CODEBYAI_API_KEY environment variable).

Codex

Follow the configure MCP guide using the standard config from above (including the CODEBYAI_API_KEY environment variable). You can also install the File MCP server using the Codex CLI:

codex mcp add file --env CODEBYAI_API_KEY={CODEBYAI_API_KEY} -- npx @codebyai/file-mcp@latest

Copilot CLI

Start Copilot CLI:

copilot

Start the dialog to add a new MCP server by running:

/mcp add

Configure the following fields and press CTR-S to save the configuration:

• Server name: file
• Server Type: [1] Local
• Command: npx
• Arguments: -y, @codebyai/file-mcp@latest
• Environment Variables: Add CODEBYAI_API_KEY with your API key value

Copilot / VS Code

Follow the MCP install guide, with the standard config from above (including the CODEBYAI_API_KEY environment variable). You can also install the File MCP server using the VS Code CLI:

code --add-mcp '{"name":"file","command":"npx","args":["@codebyai/file-mcp@latest"],"env":{"CODEBYAI_API_KEY":"{CODEBYAI_API_KEY}"}}'

Cursor

Go to Cursor Settings -> MCP -> New MCP Server. Use the config provided above (including the CODEBYAI_API_KEY environment variable).

Gemini CLI

Install the File MCP server using the Gemini CLI.

Project wide:

gemini mcp add file --env CODEBYAI_API_KEY={CODEBYAI_API_KEY} npx @codebyai/file-mcp@latest

Globally:

gemini mcp add -s user file --env CODEBYAI_API_KEY={CODEBYAI_API_KEY} npx @codebyai/file-mcp@latest

Alternatively, follow the MCP guide and use the standard config from above (including the CODEBYAI_API_KEY environment variable).

Gemini Code Assist

Follow the configure MCP guide using the standard config from above (including the CODEBYAI_API_KEY environment variable).

JetBrains AI Assistant & Junie

Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add. Use the config provided above (including the CODEBYAI_API_KEY environment variable). The same way @codebyai/file-mcp can be configured for JetBrains Junie in Settings | Tools | Junie | MCP Settings -> Add. Use the config provided above.

Visual Studio

Follow the Visual Studio MCP configuration guide and use the config provided above (including the CODEBYAI_API_KEY environment variable).

Warp

Go to Settings | AI | Manage MCP Servers -> + Add to add an MCP Server. Use the config provided above (including the CODEBYAI_API_KEY environment variable).

Your first prompt

Enter the following prompt in your MCP Client to check if everything is working:

List available knowledge base documents

Your MCP client should connect to the CodeByAI service and retrieve the knowledge base listing.

Tools

AI-Powered Analysis (1 tool)

file_understanding

Analyze and extract content from PDF, MP4, or MP3 files using Google Gemini AI.

Parameters:

• file_path (string, required): The absolute file path(s) to analyze. Multiple files can be separated by commas
• instruction (string, required): Natural language instruction for file analysis
• save_to_path (string, optional): The local file absolute path where the parsing result is saved

Returns:

• AI-generated analysis based on your instruction
• Optional: Result saved to specified file path

Note: For PDF files, this tool should only be used when the file size exceeds 2MB.

XLSX Tools (5 tools)

XLSX manipulation tools for reading, writing, filtering, and appending Excel files with multi-sheet support. Built on the xlsx library, these tools provide comprehensive Excel file operations including sheet management, row/column manipulation, and data validation.

xlsx_summary

Get XLSX document summary including all sheets with their headers and row counts.

Parameters:

• filePath (string, required): The absolute file path to the XLSX file

Returns:

• Total number of sheets in the workbook
• For each sheet:
  • Sheet name
  • Header row with column letters in format: "ColumnName(A), ColumnName(B), ..."
  • Total row count (including header row)

Example response:

XLSX Document Summary:

Total Sheets: 2

Sheet: "Users"
  Header: Name(A), Age(B), City(C)
  Total Rows: 4 (including header row)

Sheet: "Products"
  Header: Product(A), Price(B), Stock(C)
  Total Rows: 4 (including header row)

Use case: Quickly understand the structure of an XLSX file, including all available sheets and their column headers.

xlsx_row_read

Get the content of rows from a range in a specific sheet. Returns rows in markdown table format with row numbers as the first column.

Parameters:

• filePath (string, required): The absolute file path to the XLSX file
• sheet (string, required): The name of the sheet to read from
• rowNumFrom (number, required): The start row number to retrieve (1-based: 1=header, 2=first content row)
• rowNumEnd (number, required): The end row number to retrieve (1-based). Must be >= rowNumFrom

Returns:

• Markdown table format with:
  • First column: "Row No." (indicates row numbers, not part of XLSX data)
  • Remaining columns: XLSX data with headers in format "HeaderTitle(ColumnLetter)"
  • Header row always included for reference
• Note indicating the "Row No." column is not part of the XLSX file
• Total row count information

Example response:

XLSX Content from Sheet "Users" (Rows 1-3)

| Row No. | Name(A) | Age(B) | City(C) |
|---------|---------|--------|---------|
| 1       | Name    | Age    | City    |
| 2       | Alice   | 26     | New York |
| 3       | Bob     | 26     | San Francisco |

Note: The 'Row No.' column is not part of the XLSX file.
Total rows in sheet "Users": 4 (including header)

Sheet validation: If the specified sheet doesn't exist, returns an error message listing all available sheets in the format: sheet不存在,此xlsx文件拥有的sheet名称为["Sheet1","Sheet2"]

xlsx_row_edit

Modify cell values across a row range in a specific sheet. Updates the same column for all rows in the specified range with the same value.

Parameters:

• filePath (string, required): The absolute file path to the XLSX file
• sheet (string, required): The name of the sheet to modify
• rowNumFrom (number, required): The start row number to modify (1-based: 1=header, 2=first content row)
• rowNumEnd (number, required): The end row number to modify (1-based). Must be >= rowNumFrom
• colLetter (string, required): The column letter (A, B, C, ..., Z, AA, AB, ...)
• content (string, required): The new cell content to apply to all rows in the range

Returns:

• Confirmation message with the number of cells updated, the range of rows modified, and the sheet name

Example:

{
  "filePath": "/path/to/file.xlsx",
  "sheet": "Users",
  "rowNumFrom": 2,
  "rowNumEnd": 3,
  "colLetter": "B",
  "content": "26"
}

Example response:

Successfully updated 2 cell(s) in column B (rows 2-3) of sheet "Users" with value: "26"

Sheet validation: If the specified sheet doesn't exist, returns an error message listing all available sheets.

xlsx_row_filter

Filter rows in a specific sheet by searching for a keyword in a specified column. Performs case-insensitive substring matching.

Parameters:

• filePath (string, required): The absolute file path to the XLSX file
• sheet (string, required): The name of the sheet to search in
• colLetter (string, required): The column letter to search in (A, B, C, ..., Z, AA, AB, ...)
• keyword (string, required): The keyword to search for (case-insensitive substring matching)

Returns:

• When matches found:
  • Count of matching rows
  • JSON array with rowNum and columnContent for each match
  • Suggestion to use xlsx_row_read to retrieve full row details
• When no matches found:
  • Message indicating no matches were found

Example request:

{
  "filePath": "/path/to/file.xlsx",
  "sheet": "Users",
  "colLetter": "C",
  "keyword": "New"
}

Example response:

Found 1 matching row(s) in sheet "Users". Use the "xlsx_row_read" tool to retrieve the full content of a specific row.

[
  {
    "rowNum": "2",
    "columnContent": "New York"
  }
]

Features:

• Case-insensitive matching
• Substring matching
• Works with all data types (numbers, dates, text)
• Sheet validation with helpful error messages

xlsx_row_append

Append multiple rows to an XLSX sheet. If the file or sheet doesn't exist, it will be created with the first row as the header.

Parameters:

• filePath (string, required): The absolute file path to the XLSX file
• sheet (string, required): The name of the sheet to append to
• rows (string, required): JSON string representing a 2D array of rows to append (e.g., [["value1","value2"],["value3","value4"]])

Returns:

• For existing sheet: Confirmation message indicating number of rows appended and total row count
• For new sheet: Confirmation message indicating sheet created with number of rows
• For new file: Confirmation message indicating file and sheet created

Example:

{
  "filePath": "/path/to/file.xlsx",
  "sheet": "Users",
  "rows": "[[\"Alice\",\"25\",\"New York\"],[\"Bob\",\"30\",\"San Francisco\"]]"
}

Example responses:

Successfully appended 2 row(s) to sheet "Users". Total rows in sheet: 6 (including header)

Successfully created new sheet "Users" with 4 row(s). First row is set as the header.

Successfully created new XLSX file with sheet "Users" containing 4 row(s). First row is set as the header.

Features:

• Automatically creates XLSX file and/or sheet if they don't exist
• Validates column count when appending to existing sheet
• Converts all cell values to strings for consistency
• Provides helpful error messages if column count mismatch is detected

XLSX Format Details:

• Multi-sheet support: Each XLSX file can contain multiple sheets
• Sheet validation: Operations validate sheet existence and provide available sheet names on error
• Row/Column Numbering:
  • Rows: 1-based (1=header, 2=first content row, etc.)
  • Columns: Excel-style letters (A, B, C, ..., Z, AA, AB, etc.)
• Data types: All values are stored as strings
• Configuration: Tools can be disabled with --no-category-xlsx command-line flag

Configuration

Environment Variables

The File MCP server supports the following environment variables:

• CODEBYAI_API_KEY (Required): Your CodeByAI API key for authentication

  • Type: string
  • Format: Starts with sk-
  • Get your key: https://codebyai.com/console/api-keys

• CODEBYAI_BASE_URL (Optional): Override the CodeByAI API endpoint

  • Type: string
  • Default: https://codebyai.com

Set environment variables via the env property in the JSON configuration:

{
  "mcpServers": {
    "frontend": {
      "command": "npx",
      "args": ["-y", "@codebyai/frontend-mcp@latest"],
      "env": {
        "CODEBYAI_API_KEY": "{CODEBYAI_API_KEY}",
        "CODEBYAI_BASE_URL": "https://custom-domain.com"
      }
    }
  }
}

Command-Line Arguments

The Frontend MCP server supports the following command-line arguments:

• --no-category-csv (Optional): Disable all CSV-related tools

  • Type: flag (no value required)
  • Default: CSV tools are enabled
  • Usage: Add this flag to the args array to disable CSV tools if you don't need them

  {
    "mcpServers": {
      "frontend": {
        "command": "npx",
        "args": ["-y", "@codebyai/frontend-mcp@latest", "--no-category-csv"],
        "env": {
          "CODEBYAI_API_KEY": "{CODEBYAI_API_KEY}"
        }
      }
    }
  }
  

Note: For Claude Code CLI, you can add these arguments after the package name:

# Auto-detect encoding
claude mcp add frontend npx @codebyai/frontend-mcp@latest --env CODEBYAI_API_KEY={CODEBYAI_API_KEY}

# Or specify explicit encoding
claude mcp add frontend npx @codebyai/frontend-mcp@latest --env CODEBYAI_API_KEY={CODEBYAI_API_KEY}

Logging

The server logs all activities to $tmpdir/codebyai-file-mcp-log/codebyai-file-mcp-YYYY-MM-DD.log, including:

• Design file upload attempts
• Browser opening success/failure
• Conversion results
• Process management activities
• Error details
• Execution times

Error Handling

The server handles various error scenarios:

• Missing or invalid file paths
• Unsupported file formats
• Network connectivity issues
• Browser opening failures
• Conversion timeouts (5 minutes)
• Process management errors

All errors are logged and returned to the calling application with descriptive messages.

Support

For issues, questions, or feature requests, please visit CodebyAI.