# TOON MCP Server
[](https://www.npmjs.com/package/toon-mcp-server)
[](https://opensource.org/licenses/MIT)
MCP (Model Context Protocol) server for **TOON (Token-Oriented Object Notation)** encoding. Reduce LLM token usage by **50-70%** when sending structured data.
## What is TOON?
TOON is a compact data format optimized for LLM input. Instead of repeating field names for every object, it uses a header-based format:
**JSON (1041 tokens):**
```json
[
{"id": 1, "name": "Product A", "price": 99.99},
{"id": 2, "name": "Product B", "price": 149.99}
]
```
**TOON (389 tokens):**
```
[id,name,price]
1,Product A,99.99
2,Product B,149.99
```
**Result: 62% fewer tokens = 62% cost savings**
## Installation
### Quick Start (npx - no install needed)
Add to your MCP settings:
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"toon": {
"command": "npx",
"args": ["-y", "toon-mcp-server"]
}
}
}
```
**Claude Code** (`~/.claude/settings.json`):
```json
{
"mcpServers": {
"toon": {
"command": "npx",
"args": ["-y", "toon-mcp-server"]
}
}
}
```
### Global Install
```bash
npm install -g toon-mcp-server
```
Then add to your MCP settings:
```json
{
"mcpServers": {
"toon": {
"command": "toon-mcp"
}
}
}
```
### As Claude Code Skill
```bash
# Download the skill
curl -o ~/.claude/skills/toon.md https://raw.githubusercontent.com/elminson/toon-mcp/main/skills/toon.md
```
Then use `/toon` in Claude Code.
## Available Tools
### `toon_encode`
Convert data to TOON format.
**Supported formats:** JSON, CSV, TSV, XML, HTML tables, YAML
```
Input: [{"name":"Alice","age":30},{"name":"Bob","age":25}]
Output: [name,age]
Alice,30
Bob,25
```
### `toon_decode`
Convert TOON back to JSON.
### `toon_analyze`
Analyze data and show potential token/cost savings.
### `toon_optimize_prompt`
Find data sections in a prompt and convert them to TOON automatically.
## Usage Examples
### In Claude Desktop/Code (with MCP)
Just ask Claude to use the tools:
- "Encode this JSON to TOON: [...]"
- "Analyze how much I'd save converting this data to TOON"
- "Optimize this prompt for token efficiency"
### Programmatic (Node.js)
```javascript
const { ToonEncoder } = require('toon-mcp-server/src/toon-encoder');
// Encode
const data = [
{ id: 1, name: 'Test', price: 99.99 },
{ id: 2, name: 'Test 2', price: 149.99 },
];
const toon = ToonEncoder.encode(data);
// Get stats
const json = JSON.stringify(data);
const stats = ToonEncoder.getStats(json, toon);
console.log(stats.savings.percent); // "64.5%"
// Decode
const decoded = ToonEncoder.decode(toon);
```
## Benchmarks
Tested with OpenAI GPT-4o-mini:
| Dataset Size | JSON Tokens | TOON Tokens | Savings |
|--------------|-------------|-------------|---------|
| 5 items | 383 | 192 | 49.9% |
| 20 items | 1,394 | 530 | 62% |
| 50 items | 3,412 | 1,204 | 64.7% |
| 100 items | 6,800 | 2,400 | ~65% |
## Cost Savings at Scale
| Volume | GPT-4o-mini | GPT-4o | Claude Sonnet |
|--------|-------------|--------|---------------|
| 1M requests | $489 saved | $8,158 saved | $9,789 saved |
| 10M requests | $4,890 saved | $81,580 saved | $97,890 saved |
## When to Use TOON
✅ **Best for:**
- Arrays of objects with same structure (tables, lists, records)
- API responses, database results
- Large datasets sent to LLMs
- Cost optimization at scale
⚠️ **Less effective for:**
- Deeply nested, non-uniform data
- Small payloads (<5 items)
- Data with many unique field structures
## Contributing
Pull requests welcome! Please open an issue first to discuss changes.
## License
MIT
