Skip to main content
Glama
falahgs

3D Cartoon Generator & File System MCP Server

by falahgs

MCP Combined Server: 3D Cartoon Generator & File System Tools

A professional-grade server that provides two major capabilities:

  1. High-quality 3D-style cartoon image generation using Google's Gemini AI

  2. Secure file system operations for reading, writing, and managing files

3D Cartoon Generator Demo

🌟 Features

Image Generation

  • 3D Cartoon Generation: Creates high-quality 3D-style cartoon images

  • Child-Friendly Design: Focuses on colorful, playful, and engaging visuals

  • Instant Preview: Automatically opens generated images in your default browser

  • Local Storage: Saves images and previews in an organized output directory

File System Operations

  • Secure File Access: Path validation and security checks

  • Read/Write Files: Read and write text file contents

  • Directory Operations: List, create, and navigate directories

  • File Search: Find files matching patterns

System Features

  • Professional Configuration: Robust error handling and controlled logging

  • Cross-Platform Support: Intelligent file path handling for Windows, macOS, and Linux

  • Smart OS Detection: Automatically finds the best save location for each operating system

  • Security Controls: Restricted directory access through configuration

Related MCP server: MCP Filesystem Server

🛠️ Technical Stack

  • Core Framework: Model Context Protocol (MCP) SDK

  • AI Integration: Google Generative AI (Gemini)

  • Runtime: Node.js v14+

  • Language: TypeScript

  • Package Manager: npm

📋 Prerequisites

  • Node.js (v14 or higher)

  • Google Gemini API key

  • TypeScript

⚙️ Installation

  1. Clone the repository:

git clone https://github.com/falahgs/mcp-3d-style-cartoon-gen-server.git
cd mcp-3d-style-cartoon-gen-server
  1. Install dependencies:

npm install
  1. Configure environment: Create a .env file in the root directory:

GEMINI_API_KEY=your_api_key_here
ALLOWED_DIRECTORIES=/path/to/allowed/dir1,/path/to/allowed/dir2
  1. Build the project:

npm run build

🔧 Configuring Claude Desktop with MCP Server

To integrate this combined server with Claude Desktop:

  1. Locate the Configuration File:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. Add the following configuration:

{
  "mcpServers": {
    "mcp-3d-cartoon-generator": {
      "command": "node",
      "args": [
        "path/to/your/build/index.js"
      ],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "IS_REMOTE": "true",
        "SAVE_TO_DESKTOP": "true",
        "DETECT_OS_PATHS": "true",
        "ALLOWED_DIRECTORIES": "C:\\Users\\YourUsername\\Desktop,C:\\Users\\YourUsername\\Documents",
        "DEBUG": "false"
      }
    }
  }
}

Windows PowerShell Helper Script

For Windows users, you can use the included fix_claude_config.ps1 script to automatically configure Claude Desktop:

  1. Edit the script to update the path to your server build and your Gemini API key

  2. Run the script in PowerShell:

powershell -ExecutionPolicy Bypass -File .\fix_claude_config.ps1

This will create or update the configuration file with proper encoding and settings.

🚀 Available Tools

1. Image Generation Tool

{
  "name": "generate_3d_cartoon",
  "description": "Generates a 3D style cartoon image for kids based on the given prompt",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "The prompt describing the 3D cartoon image to generate"
      },
      "fileName": {
        "type": "string",
        "description": "The name of the output file (without extension)"
      }
    },
    "required": ["prompt", "fileName"]
  }
}

2. File System Tools

Read File

{
  "name": "read_file",
  "description": "Read the contents of a file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the file to read"
      }
    },
    "required": ["path"]
  }
}

Write File

{
  "name": "write_file",
  "description": "Write content to a file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the file to write"
      },
      "content": {
        "type": "string",
        "description": "Content to write to the file"
      }
    },
    "required": ["path", "content"]
  }
}

List Directory

{
  "name": "list_directory",
  "description": "List the contents of a directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the directory to list"
      }
    },
    "required": ["path"]
  }
}

Create Directory

{
  "name": "create_directory",
  "description": "Create a new directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the directory to create"
      }
    },
    "required": ["path"]
  }
}

Search Files

{
  "name": "search_files",
  "description": "Search for files matching a pattern",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Base directory to search from"
      },
      "pattern": {
        "type": "string",
        "description": "Search pattern (glob format)"
      },
      "excludePatterns": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Patterns to exclude from search (glob format)"
      }
    },
    "required": ["path", "pattern"]
  }
}

📄 Example Usage

Image Generation Examples

// Generate a 3D cartoon
{
  "name": "generate_3d_cartoon",
  "arguments": {
    "prompt": "A friendly robot playing with a cat",
    "fileName": "robot_cat_play"
  }
}

File System Examples

// Read a file
{
  "name": "read_file",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/example.txt"
  }
}

// Write a file
{
  "name": "write_file",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/new-file.txt",
    "content": "This is the content of the file."
  }
}

// List directory contents
{
  "name": "list_directory",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents"
  }
}

// Create a directory
{
  "name": "create_directory",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/new-folder"
  }
}

// Search for files
{
  "name": "search_files",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents",
    "pattern": "*.txt",
    "excludePatterns": ["temp*", "*.tmp"]
  }
}

🔒 Security Features

The server implements several security measures:

  1. Path Validation: All file paths are validated to ensure they are within allowed directories.

  2. Allowed Directories: Only directories explicitly set in the ALLOWED_DIRECTORIES environment variable can be accessed.

  3. Symlink Protection: Prevents access to directories outside the allowed scope via symlinks.

  4. Controlled Logging: Debug logs are disabled by default to prevent information leakage.

⚙️ Configuration Options

Environment Variables

Variable

Description

Default

GEMINI_API_KEY

Google Gemini API key for image generation

(Required)

ALLOWED_DIRECTORIES

Comma-separated list of allowed file system paths

User's home dir, current dir

IS_REMOTE

Run in remote mode without browser opening

false

SAVE_TO_DESKTOP

Force saving to desktop directory

false

DETECT_OS_PATHS

Enable OS-specific path detection

true

DEBUG

Enable verbose debug logging

false

🛠️ Troubleshooting

Common Issues:

  1. JSON Parsing Errors in Claude:

    • Ensure DEBUG is set to "false" to prevent logs from interfering with JSON communication

    • Check for proper JSON formatting in the Claude configuration

  2. File Access Denied:

    • Verify that the paths you're trying to access are included in ALLOWED_DIRECTORIES

    • Check file permissions on the target files/directories

  3. Images Not Saving:

    • Set SAVE_TO_DESKTOP to "true" to ensure images save to the desktop

    • Check desktop path detection in the server logs (enable DEBUG temporarily)

📄 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Available Tools

6 tools
create_directoryB

Create a new directory

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesPath to the directory to create

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It does not specify whether intermediate directories are created, what happens if the directory already exists, or any permissions required. The simple description omits critical behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no unnecessary words. It is appropriate for a simple operation, though it could arguably be expanded slightly for completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is insufficiently complete. It does not explain return values, error conditions, or path semantics (e.g., absolute vs relative), leaving gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage for the single parameter 'path' with a clear description. The tool description adds no additional meaning beyond the schema, earning a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Create a new directory' uses a specific verb and resource, clearly distinguishing it from sibling tools like read_file, write_file, or list_directory which operate on files rather than directories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as when to create a directory versus using write_file for file creation. No prerequisites or conditions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_3d_cartoonB

Generates a 3D style cartoon image for kids based on the given prompt

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe prompt describing the 3D cartoon image to generate
fileNameYesThe name of the output file (without extension)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only states the action without revealing side effects (e.g., file saving behavior, error handling, image format), leaving significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with no unnecessary words. It is front-loaded with the verb and efficiently conveys the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (2 simple params) and no output schema or annotations, the description is adequate but lacks details on output format, file location, or failure modes, leaving room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameter descriptions are already present. The description adds minor context (e.g., 'for kids') but does not enhance parameter meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it 'Generates a 3D style cartoon image for kids based on the given prompt', specifying the verb, resource, and audience. This distinct purpose differentiates it from sibling file-management tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not indicate when to use this tool over alternatives, nor does it mention prerequisites or exclusions like content restrictions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_directoryC

List the contents of a directory

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesPath to the directory to list

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must cover behavior. It only says 'list the contents' without specifying whether it returns files only, includes subdirectories, or handles non-existent paths. No safety or mutability info.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise single sentence with no wasted words. However, it may be under-specified for a tool with no annotations or output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, output schema, or error handling info, the description is incomplete. It fails to explain output format, behavior with hidden files, or error cases (e.g., invalid path).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'path', which has a clear description. The tool description adds no extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists directory contents, with a specific verb and resource. However, it does not differentiate from sibling tools like read_file or check_status, which are distinct but could be confused for similar operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. No mention of prerequisites, directory existence, or cases where it should not be used.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileB

Read the contents of a file

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesPath to the file to read

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and description does not disclose important behaviors such as encoding handling, file size limits, or whether the entire file is read at once. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise single sentence, no wasted words. Could be slightly more structured with additional behavioral notes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema or annotations. Lacks details on return format, encoding, or error handling. Incomplete for a simple file read operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description adds no extra meaning beyond the schema. Baseline 3 is appropriate as the parameter description is adequate but not enriched.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool reads the contents of a file with a specific verb and resource. It distinguishes from sibling tools like write_file and list_directory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Lacks context for prerequisites or scenarios where other tools (e.g., download_model) would be more appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_filesC

Search for files matching a pattern

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesBase directory to search from
patternYesSearch pattern (glob format)
excludePatternsNoPatterns to exclude from search (glob format)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavior. It only states 'matching a pattern' without specifying recursion, case sensitivity, or result format. Behavior is under-specified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. However, it lacks structure (e.g., separate sections for behavior vs parameters). Concise but could be better organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters, no output schema, and no annotations, the description is too brief. Does not mention output format, recursion, or edge cases. Compels the agent to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond what the schema already provides for each parameter. No additional context or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'search' and resource 'files', and distinguishes from siblings like list_directory which lists without pattern matching. However, it does not specify recursive behavior or scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like list_directory (which lists files without pattern) or read_file. The context signals show siblings but description offers no differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_fileB

Write content to a file

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesPath to the file to write
contentYesContent to write to the file

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Missing annotations and description does not disclose critical behavior such as whether the file is overwritten or appended, or what happens if the file already exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise (4 words) and front-loaded, but could benefit from a slightly more detailed one-liner.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description does not cover important aspects like return value, error conditions, or file handling behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description adds no additional meaning beyond what the schema provides; baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Write content to a file' clearly states the verb (write) and resource (file), and distinguishes from siblings like read_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., read_file), and no mention of prerequisites or specific use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.0
    • First observedcreate_directory
    • First observedgenerate_3d_cartoon
    • First observedlist_directory
    • First observedread_file
    • First observedsearch_files
    • First observedwrite_file

TDQS

B3.3/5.0

Scored across 6 tools

Disambiguation5/5

The tools clearly separate file system operations (create, list, read, search, write) from the image generation task. No two tools have overlapping purposes.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern (e.g., create_directory, generate_3d_cartoon), making it easy to predict functionality from names.

Tool Count5/5

Six tools is well-scoped for a server combining file system management and a single generative feature. Each tool serves a distinct need without unnecessary bloat.

Completeness3/5

The file system side lacks basic operations like delete_file or move_file, and the relationship between file storage and cartoon generation is unclear (e.g., no tool to save generated images). Minor gaps reduce effectiveness.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Provides secure filesystem access for AI models through the Model Context Protocol with strict path validation, file operations, directory management, and system command execution within predefined directories.
    16
    5 npm
    MIT
  • A
    license
    B
    quality
    D
    maintenance
    Enables image generation using Google Gemini models like Gemini 2.0 Flash and Imagen 3.0 with support for custom aspect ratios and negative prompts. It also allows users to list and manage generated images stored in local directories.
    2
    7 npm
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents and LLMs to perform comprehensive file system operations including CRUD, search, archive, hashing, and duplicate detection via the Model Context Protocol.
    1
    MIT