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

Ask your AI assistant: "Generate an image of a beautiful anime girl with blue hair"
The assistant will use the generate_image tool
Image data will be returned in base64 format

Character Positioning

Ask: "Create an image with a girl on the left side and a boy on the right side"
The assistant will use V4 prompt with character positioning
Characters will be placed at precise coordinates

File Saving

Ask: "Generate an anime landscape and save it to file"
Image will be automatically saved to Desktop/novelai_images/

API Key Setup

Visit NovelAI
Sign up or log in to your account
Go to Account Settings → API Keys
Generate a new API key
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

Fork the repository
Create a feature branch
Make your changes
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

NovelAI MCP Server

한국어 README

⚠️ 중요 알림

기능들

설치 방법 (한국어)

전역 설치 (권장)

로컬 설치

설정 방법 (한국어)

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

방법 2: .env 파일

MCP 설정 (한국어)

사용 예시 (한국어)

기본 이미지 생성

파일 저장 포함

캐릭터 포지셔닝

NovelAI MCP Server

⚠️ Important Note

Features

Installation

Global Installation (Recommended)

Local Installation

Configuration

Method 1: Environment Variables (Recommended)

Method 2: .env File

Method 3: WSL2 Configuration

MCP Configuration

Available Tools

🎨 generate_image

Quick Start Examples

Basic Image Generation

Character Positioning

File Saving

API Key Setup

Troubleshooting

Common Issues

Debug Mode

Development

Local Development Setup

Contributing

Limitations

Future Updates

라이선스

저자

지원

License (English)

Author (English)

Support (English)

MCP Server · Populars

MCP Server · New

🎨 `generate_image`