AI Tanka MCP Server

English | 日本語

AI Tanka is an MCP (Model Context Protocol) server that generates traditional Japanese tanka poems (5-7-5-7-7 syllable format) using multiple Large Language Models.

Features

• Multiple LLM Provider Support

  • Anthropic (Claude)
  • OpenAI (GPT)
  • Google Gemini
  • Grok (xAI)

• Three Generation Modes

  • Generate tanka from input text
  • Generate tanka from a theme
  • Generate tanka with a random theme

• Customizable Options

  • Tone/Atmosphere (joyful, melancholy, passionate, serene, nostalgic, romantic, philosophical)
  • Style (classical, modern, traditional, contemporary)
  • Season (spring, summer, autumn, winter, none)
  • Model Strategy (specific, all providers, random)

• MCP Server & CLI Tool

  • Use with MCP clients like Claude Desktop
  • Standalone CLI tool

Installation

npm install -g ai-tanka-mcp

Or build locally for development:

git clone https://github.com/ex-takashima/tanka-mcp.git
cd tanka-mcp
npm install
npm run build

Setup

1. Configure API Keys

You need at least one LLM provider API key.

Using Environment Variables

Create a .env file:

cp .env.example .env

Edit .env to add your API keys:

# Default provider
DEFAULT_PROVIDER=anthropic

# Anthropic (Claude)
ANTHROPIC_API_KEY=your-api-key-here
ANTHROPIC_MODEL=claude-haiku-4-5-20251001

# OpenAI
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gpt-5-2025-08-07

# Google Gemini
GOOGLE_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-2.5-flash

# Grok (xAI)
GROK_API_KEY=your-api-key-here
GROK_MODEL=grok-4-fast

Using Configuration File

Create .tanka-config.json in your home or project directory:

{
  "llm": {
    "anthropic": {
      "apiKey": "your-api-key",
      "model": "claude-haiku-4-5-20251001"
    },
    "openai": {
      "apiKey": "your-api-key",
      "model": "gpt-5-2025-08-07"
    },
    "gemini": {
      "apiKey": "your-api-key",
      "model": "gemini-2.5-flash"
    },
    "grok": {
      "apiKey": "your-api-key",
      "model": "grok-4-fast"
    }
  }
}

2. Use as MCP Server

Add to Claude Desktop config (claude_desktop_config.json):

Using npx (Recommended)

The easiest way to use the MCP server without building locally:

{
  "mcpServers": {
    "ai-tanka": {
      "command": "npx",
      "args": ["-y", "ai-tanka-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here",
        "ANTHROPIC_MODEL": "claude-haiku-4-5-20251001"
      }
    }
  }
}

Benefits:

• No need to build locally
• Always uses the latest version
• No need to specify paths

Local Build Configuration (Single Provider)

For local development or when using a local build:

{
  "mcpServers": {
    "ai-tanka": {
      "command": "node",
      "args": ["/path/to/ai-tanka-mcp/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here",
        "ANTHROPIC_MODEL": "claude-haiku-4-5-20251001"
      }
    }
  }
}

Full Configuration (Multiple Providers with npx)

{
  "mcpServers": {
    "ai-tanka": {
      "command": "npx",
      "args": ["-y", "ai-tanka-mcp"],
      "env": {
        "DEFAULT_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key-here",
        "ANTHROPIC_MODEL": "claude-haiku-4-5-20251001",
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "OPENAI_MODEL": "gpt-5-2025-08-07",
        "GOOGLE_API_KEY": "your-google-api-key-here",
        "GEMINI_MODEL": "gemini-2.5-flash",
        "GROK_API_KEY": "your-grok-api-key-here",
        "GROK_MODEL": "grok-4-fast"
      }
    }
  }
}

Recommended Models (2025):

• ANTHROPIC_MODEL - claude-haiku-4-5-20251001 (Best balance: $1/$5 per 1M tokens)
  • Alternative: claude-sonnet-4-5-20250929 (Highest quality: $3/$15)
• OPENAI_MODEL - gpt-5-2025-08-07 (High quality: $1.25/$10 per 1M tokens)
  • Alternative: gpt-5-mini (Cost-effective: $0.25/$2)
• GEMINI_MODEL - gemini-2.5-flash (Fast & cheap: $0.30/$2.50 per 1M tokens)
  • Alternative: gemini-2.5-pro (Higher quality: $1.25/$10)
• GROK_MODEL - grok-4-fast (Very cheap: $0.20-0.40/$0.50-1.00 per 1M tokens)
  • Alternative: grok-4 (Higher quality: $3/$15)

Usage

CLI Tool

Generate from Text

ai-tanka from-text "Today is a beautiful sunny day. The cherry blossoms are in full bloom."

With options:

ai-tanka from-text "Autumn evening" \
  --tone melancholy \
  --style classical \
  --season autumn \
  --provider anthropic

Generate from Theme

ai-tanka from-theme "Sadness of parting" --tone melancholy

Generate Random Theme

ai-tanka random --style modern

Generate with All Models

ai-tanka from-theme "Spring arrival" --model-strategy all

Check Available Providers

ai-tanka providers

MCP Tools

Available tools for MCP clients:

1. generate_tanka_from_text - Generate tanka from input text
2. generate_tanka_from_theme - Generate tanka from a theme
3. generate_tanka_random - Generate tanka with random theme

Example (in Claude Desktop):

Please create a tanka about cherry blossoms in spring

Claude Code will automatically use the generate_tanka_from_theme tool.

CLI Options

Common Options

• -t, --tone <tone> - Tone/Atmosphere

  • joyful - Joyful
  • melancholy - Melancholy
  • passionate - Passionate
  • serene - Serene
  • nostalgic - Nostalgic
  • romantic - Romantic
  • philosophical - Philosophical

• -s, --style <style> - Style

  • classical - Classical (Manyoshu/Kokin Wakashu style)
  • modern - Modern
  • traditional - Traditional
  • contemporary - Contemporary

• --season <season> - Season

  • spring - Spring
  • summer - Summer
  • autumn - Autumn
  • winter - Winter
  • none - No season

• -p, --provider <provider> - LLM Provider

  • anthropic
  • openai
  • gemini
  • grok

• -m, --model-strategy <strategy> - Model Selection Strategy

  • specific - Use specific provider (default)
  • all - Generate with all available providers
  • random - Randomly select a provider

Output Format

{
  "success": true,
  "results": [
    {
      "tanka": "Cherry blossoms\nDancing in spring breeze\nSo fleeting\nBeauty in transience\nMoment of perfection",
      "reading": "さくらばな まいちるはるの かぜのなか はかなきいのち うつくしきかな",
      "translation": "Cherry blossoms dancing in the spring breeze, their fleeting life so beautiful",
      "explanation": "A poem expressing the ephemeral beauty of cherry blossoms in spring. Through the image of petals dancing in the wind, it captures the contrast between life's transience and its beauty.",
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "metadata": {
        "mode": "from-theme",
        "tone": "melancholy",
        "style": "classical",
        "season": "spring",
        "generatedAt": "2025-01-15T12:34:56.789Z"
      }
    }
  ],
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Development

Build

npm run build

Development Mode (Watch)

npm run watch

Test

npm test

Test (Watch Mode)

npm run test:watch

License

MIT License - See LICENSE file for details.

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

Support

If you encounter any issues, please report them on GitHub Issues.