Metadata-Version: 2.4
Name: nanobanana-2-polzaia-mcp-server
Version: 0.4.7
Summary: An MCP server for Nano Banana image generation through the Polza media API
Project-URL: Homepage, https://github.com/ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server
Project-URL: Repository, https://github.com/ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server.git
Project-URL: Documentation, https://github.com/ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server#readme
Project-URL: Bug Tracker, https://github.com/ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server/issues
Author-email: zhongwei <lizhongwei.nkcs@gmail.com>
License: MIT
License-File: LICENSE
Keywords: 4k,fastmcp,image-generation,mcp,nano-banana,polza,polza-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.11.0
Requires-Dist: pillow>=10.4.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.1
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: fastmcp>=2.11.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.4.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.20.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: responses>=0.23.0; extra == 'test'
Description-Content-Type: text/markdown

# Nano Banana 2 Polza MCP Server

`mcp-name: io.github.ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server`

MCP server for image generation and editing through `Polza`, using:

- `google/gemini-3.1-flash-image-preview` as the default Nano Banana 2 model
- `google/gemini-3-pro-image-preview` for higher-quality compositions
- `google/gemini-2.5-flash-image` for faster draft generation

This project exposes MCP tools like:

- `generate_image`
- `upload_file`
- `output_stats`
- `maintenance`

## What Users Need

- `Claude Code` or another MCP client
- `uv`
- `Python 3.11+`
- a `POLZA_AI_API_KEY`

## Install in 2 Minutes

For `Claude Code` / `VS Code`, the fastest setup is:

1. Install `uv`
2. Create a `.mcp.json` file in your project root
3. Paste this config and add your Polza key

```json
{
  "mcpServers": {
    "nanobanana-polza": {
      "command": "uvx",
      "args": ["nanobanana-2-polzaia-mcp-server@latest"],
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here",
        "POLZA_BASE_URL": "https://polza.ai/api",
        "IMAGE_OUTPUT_DIR": "/Users/yourname/Documents/nanobanana"
      }
    }
  }
}
```

Then restart Claude Code / VS Code.

## Local Development

```bash
git clone https://github.com/ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server.git
cd nanobanana-2-polzaia-mcp-server
uv sync
cp .env.example .env
```

Set at minimum:

```env
POLZA_AI_API_KEY=your_polza_api_key
POLZA_BASE_URL=https://polza.ai/api
IMAGE_OUTPUT_DIR=/absolute/path/to/output
```

Run locally:

```bash
uv run python -m nanobanana_2_polzaia_mcp_server.server
```

## Claude Code / VS Code

If the package is published to PyPI, the easy install path is a project-level `.mcp.json`:

```json
{
  "mcpServers": {
    "nanobanana-polza": {
      "command": "uvx",
      "args": ["nanobanana-2-polzaia-mcp-server@latest"],
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here",
        "POLZA_BASE_URL": "https://polza.ai/api",
        "IMAGE_OUTPUT_DIR": "/Users/demo/Documents/nanobanana"
      }
    }
  }
}
```

If the user runs from source instead of a published package:

```json
{
  "mcpServers": {
    "nanobanana-polza-local": {
      "command": "uv",
      "args": ["run", "python", "-m", "nanobanana_2_polzaia_mcp_server.server"],
      "cwd": "/absolute/path/to/nanobanana-2-polzaia-mcp-server",
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here",
        "POLZA_BASE_URL": "https://polza.ai/api",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/output"
      }
    }
  }
}
```

## Claude Desktop

On macOS, add the same server to:

`~/Library/Application Support/Claude/claude_desktop_config.json`

Example:

```json
{
  "mcpServers": {
    "nanobanana-polza": {
      "command": "uvx",
      "args": ["nanobanana-2-polzaia-mcp-server@latest"],
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here",
        "POLZA_BASE_URL": "https://polza.ai/api",
        "IMAGE_OUTPUT_DIR": "/Users/demo/Documents/nanobanana"
      }
    }
  }
}
```

## What Still Needs To Be Published

To make installation as easy as the screenshot flow:

1. Publish the Python package to `PyPI`
2. Update repository URLs in `pyproject.toml` and `server.json`
3. Publish `server.json` to the `MCP Registry`

The registry only stores metadata. The actual package still needs to exist on PyPI.

## Publish Checklist

Before publishing:

1. Create the GitHub repo `ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server`
2. Bump the version
3. Build and test:

```bash
PYTHONPYCACHEPREFIX=/tmp/pycache python3 -m compileall nanobanana_2_polzaia_mcp_server tests
uv build
```

4. Publish to PyPI

```bash
uv publish
```

5. Publish `server.json` with `mcp-publisher`

```bash
brew install mcp-publisher
mcp-publisher login
mcp-publisher publish
```

## Backend Notes

This server uses:

- `POST /v1/media`
- `GET /v1/media/{id}`
- `POST /v1/storage/upload`
- `GET /v1/storage/files/{id}`
- `DELETE /v1/storage/files/{id}`

through the Polza API.
