Metadata-Version: 2.4
Name: figurify-mcp
Version: 0.2.1
Summary: Ship-ready MCP server for Gemini + Imagen diagram/plot generation. Runs on Claude, ChatGPT, VSCode Copilot, Cursor.
Project-URL: Homepage, https://github.com/genaimanoj/figurify-mcp
Project-URL: Repository, https://github.com/genaimanoj/figurify-mcp
Project-URL: Issues, https://github.com/genaimanoj/figurify-mcp/issues
Project-URL: Changelog, https://github.com/genaimanoj/figurify-mcp/blob/main/CHANGELOG.md
Author-email: Manoj Bhandari <genaimanoj@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: chatgpt,claude,diagram,gemini,imagen,infographic,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastmcp>=0.2.0
Requires-Dist: google-genai>=1.0
Requires-Dist: matplotlib>=3.8
Requires-Dist: mcp>=1.0.0
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# figurify-mcp

[![PyPI](https://img.shields.io/pypi/v/figurify-mcp.svg)](https://pypi.org/project/figurify-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/figurify-mcp.svg)](https://pypi.org/project/figurify-mcp/)
[![CI](https://github.com/genaimanoj/figurify-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/genaimanoj/figurify-mcp/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

MCP server for **Google Gemini + Imagen** image generation. Works with Claude Desktop, Claude Code, Cursor, VSCode Copilot, and any MCP-compatible host.

- 5 generation tools — diagrams, infographics, paper figures, matplotlib plots, VLM judging
- Smart model routing across **Gemini 2.5 / 3 / 3.1** + **Imagen 4 / Nano Banana**
- **1K by default** to stay under Claude's 1 MB inline tool-result cap
- Stdio + streamable HTTP transports

---

## Install

```bash
pip install figurify-mcp        # or: uv pip install figurify-mcp
```

Get a free Gemini API key: [aistudio.google.com/apikey](https://aistudio.google.com/apikey)

## Configure your host

### Claude Desktop — `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "figurify": {
      "command": "uvx",
      "args": ["figurify-mcp"],
      "env": { "GOOGLE_API_KEY": "your-key" }
    }
  }
}
```

### Claude Code / Cursor

```bash
claude mcp add figurify -s user \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  -- uvx figurify-mcp
```

### VSCode Copilot — `.vscode/mcp.json`

```json
{
  "servers": {
    "figurify": {
      "command": "uvx",
      "args": ["figurify-mcp"],
      "env": { "GOOGLE_API_KEY": "your-key" }
    }
  }
}
```

Restart the host. The tools appear automatically.

---

## Tools

| Tool | What it does | Typical cost |
|---|---|---|
| `create_simple_diagram` | Quick prompt → image | ~$0.04 |
| `create_infographic` | Topic → styled poster (VLM layout + Imagen render) | ~$0.12 |
| `create_methodology_diagram` | Paper figure with N critique rounds | ~$0.25 |
| `create_statistical_plot` | Data → matplotlib chart via VLM codegen | ~$0.002 |
| `evaluate_diagram` | VLM-as-judge comparison of two diagrams | ~$0.015 |

**Meta** (save host context): `search_tools`, `describe_tool`, `recommend_model`, `estimate_cost`, `list_available_models`.

**Prompts**: `draft_methodology_figure`, `plan_visual_output`.

**Resources**: `figurify://styles/methodology_guidelines`, `figurify://styles/infographic_guidelines`, `figurify://catalog/models`.

Images return as MCP `ImageContent` blocks with `audience: ["user"]` — they render inline in every compliant host.

---

## Configuration

All env vars are optional.

| Variable | Default | Purpose |
|---|---|---|
| `GOOGLE_API_KEY` | *(required)* | Gemini + Imagen API key |
| `FIGURIFY_OUTPUT_DIR` | `~/.figurify/outputs` | Where generated PNGs are saved |
| `FIGURIFY_VLM_MODEL` | *(auto-routed)* | Pin a specific VLM model |
| `FIGURIFY_IMAGE_MODEL` | *(auto-routed)* | Pin a specific image model |
| `FIGURIFY_MAX_METHODOLOGY_ITERATIONS` | `4` | Upper bound for critique loops |

## Transports

```bash
figurify-mcp                                            # stdio (default)
figurify-mcp --transport http --host 0.0.0.0 --port 8765
```

---

## Security

This server runs **VLM-generated matplotlib code** in a subprocess. Shipped mitigations:

- AST + pattern allowlist rejects any code importing `os`, `subprocess`, `socket`, `urllib`, `requests`, `pickle`, etc.
- `python -I` isolated mode, minimal env, POSIX `setrlimit` (512 MB RAM / 120 s CPU / 100 MB fsize)
- `load_image` restricts filesystem reads to `{output_dir, /tmp, CWD}` — no path traversal
- API-key patterns and home paths stripped from every error message

Report vulnerabilities privately: **genaimanoj@gmail.com**. Full threat model in [SECURITY.md](SECURITY.md).

## Development

```bash
git clone https://github.com/genaimanoj/figurify-mcp
cd figurify-mcp
uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'
cp .env.example .env   # set GOOGLE_API_KEY
pytest -q              # 64 tests, ~6 s
```

Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT © 2026 Manoj Bhandari. See [LICENSE](LICENSE).
