NovelAI MCP Server

[English README below]

한국어 README

Model Context Protocol (MCP) 서버로 NovelAI 이미지 생성을 사용하세요. 캐릭터 포지셔닝과 V4 프롬프트 같은 고급 기능으로 고품질 애니메 아트를 만들 수 있습니다.

⚠️ 중요 알림

현재 API 제한: NovelAI API는 현재 nai-diffusion-3 모델만 지원합니다. 고급 V4.5 기능은 웹 인터페이스에서는 사용 가능하지만 아직 API에서는 지원되지 않습니다. NovelAI가 API 지원을 확장하면 즉시 업데이트하겠습니다!

기능들

• 🎨 AI 이미지 생성 NovelAI의 nai-diffusion-3 모델 사용

• 🎭 고급 캐릭터 포지셔닝 V4 프롬프트 포맷으로

• 💾 직접 파일 저장 바로 데스크톱에

• 🔧 간단한 설정 환경변수나 .env 파일로

• 🌐 크로스플랫폼 지원 (Windows, Linux, macOS)

• 📦 설정 필요 없음 npm으로 바로 설치

• ⚡ 고급 파라미터: dynamic thresholding, variety boost, quality toggle

설치 방법 (한국어)

전역 설치 (권장)

npm install -g novelai-mcp-server

로컬 설치

npm install novelai-mcp-server

설정 방법 (한국어)

방법 1: 환경변수 (권장)

Windows:

setx NOVELAI_API_KEY "당신의-API-키"

Linux/macOS:

export NOVELAI_API_KEY="당신의-API-키"
echo 'export NOVELAI_API_KEY="당신의-API-키"' >> ~/.bashrc

방법 2: .env 파일

서버를 실행하는 디렉터리에 .env 파일 생성:

NOVELAI_API_KEY=당신의-API-키

MCP 설정 (한국어)

MCP 클라이언트 설정 파일에 추가 (보통 ~/.config/claude/mcp.json):

{
  "mcpServers": {
    "novelai": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "novelai-mcp-server"]
    }
  }
}

사용 예시 (한국어)

기본 이미지 생성

아름다운 애니메 소녀 이미지 생성해줘

파일 저장 포함

애니메 일몰 노을 이미지 생성하고 파일로 저장해줘

캐릭터 포지셔닝

왼쪽에는 금발 여자아이, 오른쪽에는 검은머리 남자아이가 있는 공원 이미지 생성해줘

NovelAI MCP Server

Model Context Protocol (MCP) server for NovelAI image generation. Create high-quality anime art with advanced features like character positioning and V4 prompts.

⚠️ Important Note

Current API Limitation: NovelAI's API currently supports nai-diffusion-3 model only. Advanced V4.5 features are available on the web interface but not yet in the API. We'll update as soon as NovelAI expands API support!

Features

• 🎨 AI Image Generation using NovelAI's nai-diffusion-3 model

• 🎭 Advanced Character Positioning with V4 prompt format

• 💾 Direct File Saving to your Desktop

• 🔧 Easy Setup with environment variables or .env file

• 🌐 Cross-platform support (Windows, Linux, macOS)

• 📦 Zero-config installation via npm

• ⚡ Advanced Parameters: dynamic thresholding, variety boost, quality toggle

Installation

Global Installation (Recommended)

npm install -g novelai-mcp-server

Local Installation

npm install novelai-mcp-server

Configuration

Method 1: Environment Variables (Recommended)

Windows:

setx NOVELAI_API_KEY "your-api-key-here"

Linux/macOS:

export NOVELAI_API_KEY="your-api-key-here"
echo 'export NOVELAI_API_KEY="your-api-key-here"' >> ~/.bashrc

Method 2: .env File

Create a .env file in the same directory where you run the server:

NOVELAI_API_KEY=your-api-key-here

Method 3: WSL2 Configuration

echo 'export NOVELAI_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

MCP Configuration

Add to your MCP client configuration file (usually ~/.config/claude/mcp.json or similar):

{
  "mcpServers": {
    "novelai": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "novelai-mcp-server"]
    }
  }
}

Available Tools

🎨 generate_image

Generate high-quality anime images using NovelAI's nai-diffusion-3 model.

Basic Parameters:

• prompt (required): Text prompt for image generation

• model: Model to use (default: "nai-diffusion-3") ⚠️ Only supported model currently

• sampler: Sampler algorithm (default: "k_euler_ancestral")

• seed: Random seed (default: -1 for random)

• negative_prompt: Negative prompt to avoid unwanted elements

• n_samples: Number of images to generate (default: 1)

• width: Image width (default: 512)

• height: Image height (default: 768)

• scale: CFG scale - prompt adherence (default: 5.0)

• steps: Number of generation steps (default: 28)

🎭 Advanced Features:

• v4_prompt: V4 prompt format for character positioning

  • base_caption: Base scene description

  • char_captions: Array of characters with precise x,y coordinates (0-1 range)

• save_to_file: Save image to local file (default: false)

• output_dir: Custom save directory (default: Desktop/novelai_images)

• filename: Custom filename (without extension)

• dynamic_thresholding: Enable for better contrast

• variety_boost: Enable for more diverse results

• quality_toggle: Enable quality enhancement

📱 Example Usage:

Basic:

Generate an image of a beautiful anime girl in a garden, masterpiece, best quality

Character Positioning:

{
  "prompt": "masterpiece, anime style, park scene",
  "v4_prompt": {
    "base_caption": "masterpiece, anime style, park scene",
    "char_captions": [
      {
        "centers": [{"x": 0.3, "y": 0.4}],
        "char_caption": "1girl, blonde hair, blue eyes, smiling, summer dress"
      }
    ]
  },
  "save_to_file": true
}

With File Saving:

Generate image of anime sunset, save to file, use dynamic thresholding

Quick Start Examples

Basic Image Generation

1. Ask your AI assistant: "Generate an image of a beautiful anime girl with blue hair"

2. The assistant will use the generate_image tool

3. Image data will be returned in base64 format

Character Positioning

1. Ask: "Create an image with a girl on the left side and a boy on the right side"

2. The assistant will use V4 prompt with character positioning

3. Characters will be placed at precise coordinates

File Saving

1. Ask: "Generate an anime landscape and save it to file"

2. Image will be automatically saved to Desktop/novelai_images/

API Key Setup

1. Visit NovelAI

2. Sign up or log in to your account

3. Go to Account Settings → API Keys

4. Generate a new API key

5. Copy the key and set it using one of the configuration methods above

Troubleshooting

Common Issues

"API key not found"

• Ensure NOVELAI_API_KEY is set correctly

• Check .env file is in the right directory

• Verify environment variable is properly exported

"Model doesn't exist" error

• Only use "nai-diffusion-3" model currently

• NovelAI API doesn't support V4.5 yet

Image generation fails

• Check your NovelAI account balance

• Verify API key is valid and active

• Check internet connection

File saving fails

• Ensure Desktop directory exists

• Check write permissions

• Verify output directory path is valid

Debug Mode

Set DEBUG environment variable for detailed logs:

DEBUG=novelai-mcp-server:* npx -y novelai-mcp-server

Development

Local Development Setup

git clone https://github.com/ginishuh/novelai-mcp-server.git
cd novelai-mcp-server
npm install
npm start

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Submit a pull request

Limitations

• Model Support: Only nai-diffusion-3 currently available via API

• Rate Limits: Subject to NovelAI's API rate limiting

• Account Requirements: Valid NovelAI subscription required

Future Updates

We're actively monitoring NovelAI's API updates and will add support for:

• V4.5 models when available in API

• Additional samplers and parameters

• Enhanced character positioning features

• Text generation capabilities

라이선스

MIT License - LICENSE 파일 참조

저자

ginishuh - GitHub

지원

• 📧 이슈: GitHub Issues

• 🐛 버그 리포트: 이슈 생성

Made with ❤️ by ginishuh | Version 0.1.0

License (English)

MIT License - see LICENSE file for details

Author (English)

ginishuh - GitHub

Support (English)

• 📧 Issues: GitHub Issues

• 🐛 Bug Reports: Create Issue

Made with ❤️ by ginishuh | Version 0.1.0