🌮 TACO MCP Server - Tabela Nutricional Brasileira para Agentes de IA

Servidor MCP (Model Context Protocol) para a Tabela TACO de composição de alimentos brasileiros.

Conecte agentes de inteligência artificial à maior base de dados nutricionais do Brasil. Calcule calorias, proteínas, carboidratos e gorduras de 597 alimentos brasileiros oficiais. Ideal para apps de dieta, coaching nutricional e controle de macros.

📖 English Version

🚀 Instalação Rápida

Requisito: Python 3.11+

Opção 1: Instalação Simples (Recomendada)

pip install git+https://github.com/matheusbuniotto/taco-mcp.git

Pronto! O comando taco-mcp está disponível globalmente.

Opção 2: Com uv (Sem instalação global)

Se você usa uv:

# Executar diretamente sem instalar
uvx --from git+https://github.com/matheusbuniotto/taco-mcp.git taco-mcp

# Ou instalar no ambiente atual
uv pip install git+https://github.com/matheusbuniotto/taco-mcp.git

Opção 3: Desenvolvimento (Clone)

git clone https://github.com/matheusbuniotto/taco-mcp.git
cd taco-mcp
pip install -e "."

🔗 Integrações

Hermes Agent (Configuração Simples)

Passo 1: Instale o pacote

pip install git+https://github.com/matheusbuniotto/taco-mcp.git

Passo 2: Adicione ao ~/.hermes/config.yaml:

mcp_servers:
  taco:
    command: "taco-mcp"
    timeout: 30

Pronto! Reinicie o Hermes e as ferramentas estarão disponíveis.

Configuração Alternativa (sem instalação global)

Se preferir não instalar globalmente, use com uv:

mcp_servers:
  taco:
    command: "uvx"
    args: ["--from", "git+https://github.com/matheusbuniotto/taco-mcp.git", "taco-mcp"]
    timeout: 30

Ou com Python diretamente (requer clone):

mcp_servers:
  taco:
    command: "python"
    args: ["-m", "taco_mcp.server"]
    timeout: 30

As ferramentas aparecerão como:

mcp_taco_search_food - Buscar alimentos
mcp_taco_get_food - Detalhes do alimento
mcp_taco_calculate_macros - Calcular macros por grama
mcp_taco_calculate_meal_macros - Calcular refeição completa
mcp_taco_add_custom_food - Adicionar alimento customizado
mcp_taco_list_custom_foods - Listar customizados
mcp_taco_delete_custom_food - Remover customizado

Claude Desktop / Outros Clientes MCP

Clique-e-Configure:

Edite seu arquivo de configuração do Claude Desktop:

Windows: %APPDATA%\Claude\settings.json
Mac: ~/Library/Application Support/Claude/settings.json
Linux: ~/.config/Claude/settings.json

Adicione:

{
  "mcpServers": {
    "taco": {
      "command": "taco-mcp"
    }
  }
}

Reinicie o Claude Desktop.

📊 Base de Dados TACO

A TACO (Tabela Brasileira de Composição de Alimentos) é mantida pela UNICAMP/NEPA e é a referência oficial para nutrição no Brasil.

597 alimentos em mais de 20 categorias
28 componentes nutricionais por alimento
Valores por 100g de porção comestível
Fonte oficial: https://www.nepa.unicamp.br/taco/

Categorias de Alimentos

Cereais e derivados              | Frutas e derivados
Verduras, hortaliças             | Gorduras e óleos
Pescados e frutos do mar         | Carnes e derivados
Leite e derivados                | Bebidas (alcoólicas e não)
Ovos e derivados                 | Produtos açucarados
Miscelâneas                      | Alimentos industrializados
Leguminosas                      | Nozes e sementes

🛠️ Ferramentas Disponíveis

Busca e Consulta

`search_food` - Buscar Alimentos

Busque alimentos por nome em português. Retorna candidatos do TACO e alimentos customizados.

{
  "query": "arroz",
  "limit": 5
}

Resposta:

{
  "query": "arroz",
  "normalized_query": "arroz",
  "results": [
    {
      "food_id": 3,
      "description": "Arroz, tipo 1, cozido",
      "category": "Cereais e derivados",
      "per_100g": {
        "kcal": 128.0,
        "protein_g": 2.5,
        "carbs_g": 28.1,
        "fat_g": 0.2,
        "fiber_g": 1.6,
        "sodium_mg": 1.0
      },
      "match_reason": "alias",
      "confidence": 1.0
    }
  ]
}

`get_food` - Detalhes do Alimento

{
  "food_id": 3
}

`calculate_macros` - Calcular Macronutrientes

Calcule calorias e macros para uma quantidade específica em gramas.

{
  "food_id": 3,
  "grams": 150
}

Resposta:

{
  "food_id": 3,
  "description": "Arroz, tipo 1, cozido",
  "grams": 150.0,
  "macros": {
    "kcal": 192.0,
    "protein_g": 3.75,
    "carbs_g": 42.15,
    "fat_g": 0.3,
    "fiber_g": 2.4,
    "sodium_mg": 1.5
  }
}

`calculate_meal_macros` - Calcular Refeição Completa

{
  "items": [
    {"food_id": 3, "grams": 150},
    {"food_id": 410, "grams": 100}
  ]
}

Resposta:

{
  "source": "TACO",
  "items": [...],
  "total": {
    "kcal": 351.0,
    "protein_g": 35.75,
    "carbs_g": 42.15,
    "fat_g": 2.8
  }
}

Alimentos Customizados

`add_custom_food` - Adicionar Suplemento ou Marca

Adicione whey protein, creatina, barras de proteína ou receitas caseiras.

{
  "name": "Whey Protein Isolado Dux",
  "kcal_per_100g": 374,
  "protein_g_per_100g": 87,
  "fat_g_per_100g": 2,
  "carbs_g_per_100g": 3,
  "category": "Suplementos",
  "notes": "1 scoop = 30g"
}

IDs de alimentos customizados começam em 100000 para evitar conflito com o TACO (1-597).

`list_custom_foods` - Listar Customizados

{
  "limit": 50
}

`delete_custom_food` - Remover Alimento

{
  "food_id": 100001
}

🎯 Exemplos de Uso

Diário Alimentar em Linguagem Natural

Usuário: "Comi 150g de arroz e 100g de frango"

Fluxo do agente:

# 1. Extrai os itens
itens = [
    ("arroz", 150),
    ("frango", 100)
]

# 2. Busca os alimentos
search_food("arroz")     # Retorna: Arroz, tipo 1, cozido (ID 3)
search_food("frango")    # Retorna: Frango, peito, grelhado (ID 410)

# 3. Calcula a refeição
calculate_meal_macros([
    {"food_id": 3, "grams": 150},
    {"food_id": 410, "grams": 100}
])

# 4. Apresenta ao usuário
# "Total: 351 kcal (35.8g proteína, 42.2g carboidratos, 2.8g gorduras)"

Adicionando Suplementos

Usuário: "Cadastra meu whey: 110 kcal, 24g proteína por scoop"

add_custom_food(
    name="Meu Whey Protein",
    kcal_per_100g=367,  # 110 * 100/30
    protein_g_per_100g=80,
    category="Suplementos",
    notes="1 scoop = 30g"
)

🌐 Sistema de Apelidos (Aliases)

Mapeamento de termos comuns para facilitar busca em linguagem natural:

# data/aliases.yaml
arroz: 3                    # Arroz tipo 1 cozido
arroz branco: 3
arroz integral: 1
frango: 410                 # Peito grelhado
peito de frango: 410
ovo: 199                    # Ovo cozido
banana: 78                  # Banana prata
feijao: 175                 # Feijão carioca
batata: 156                 # Batata inglesa cozida
pao: 51                     # Pão francês

Os aliases garantem que quando o usuário diz "comi arroz", o sistema retorne o preparo mais comum (arroz branco cozido) ao invés de exigir correspondência exata.

🎨 Arquitetura

├── CSV TACO (597 alimentos)
│   └── download_taco.py
├── Banco SQLite
│   ├── tabela foods (dados TACO)
│   ├── tabela foods_fts (busca FTS5)
│   ├── tabela custom_foods (alimentos do usuário)
│   └── build_db.py
├── Servidor MCP
│   ├── search_food (FTS5 + aliases)
│   ├── calculate_macros
│   ├── calculate_meal_macros
│   └── Gerenciamento de custom_foods
└── Cliente MCP (Hermes, Claude, etc.)

Decisões de Design

Decisão	Motivação
SQLite + FTS5	Sem serviços externos, busca full-text rápida
Sem embeddings	Base pequena (~600 itens); FTS5 é suficiente
Offset de IDs (100000+)	Evita colisão com IDs oficiais do TACO
Camada de aliases	Lida com variação de linguagem natural
Normalização PT-BR	Remove acentos para melhor matching

📁 Estrutura do Projeto

taco-mcp/
├── data/
│   ├── raw/
│   │   └── alimentos.csv          # Dados fonte TACO
│   ├── processed/
│   │   └── taco.sqlite            # Banco SQLite
│   └── aliases.yaml              # Apelidos de alimentos
├── scripts/
│   ├── download_taco.py          # Download do CSV TACO
│   └── build_db.py               # Constrói banco SQLite
├── src/taco_mcp/
│   ├── __init__.py
│   ├── server.py                 # Implementação MCP
│   ├── db.py                     # Operações de banco
│   ├── schemas.py                # Modelos Pydantic
│   └── normalize.py              # Normalização de texto
├── tests/
│   ├── test_db.py
│   └── test_normalize.py
├── pyproject.toml
├── README.md
├── README_EN.md
└── LICENSE

🧪 Desenvolvimento

Executar Testes

pip install pytest
python -m pytest tests/ -v

Adicionar Aliases

Edite data/aliases.yaml:

meu_apelido_customizado: 100001
# Mapeie termos comuns para IDs de alimentos

Reconstruir Base de Dados

python scripts/download_taco.py --force
python scripts/build_db.py

📋 Roadmap

Construtor de receitas (combinar múltiplos alimentos)
Integração com busca por código de barras
Estimativa de porções ("1 prato", "1 concha", "1 fatia")
Acompanhamento de metas diárias
Suporte multilíngue (descrições em inglês)

📋 Licença

MIT License - veja LICENSE

🪝 Agradecimentos

UNICAMP/NEPA por manter a base TACO
Model Context Protocol pela especificação MCP
machine-learning-mocha pela exportação CSV no GitHub

📞 Suporte

🐛 Issues: github.com/matheusbuniotto/taco-mcp/issues
📝 Discussões: GitHub Discussions

Feito com ❤️ para a nutrição brasileira

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
data		data
scripts		scripts
src/taco_mcp		src/taco_mcp
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

🌮 TACO MCP Server - Tabela Nutricional Brasileira para Agentes de IA

🚀 Instalação Rápida

Opção 1: Instalação Simples (Recomendada)

Opção 2: Com uv (Sem instalação global)

Opção 3: Desenvolvimento (Clone)

🔗 Integrações

Hermes Agent (Configuração Simples)

Configuração Alternativa (sem instalação global)

Claude Desktop / Outros Clientes MCP

📊 Base de Dados TACO

Categorias de Alimentos

🛠️ Ferramentas Disponíveis

Busca e Consulta

search_food - Buscar Alimentos

get_food - Detalhes do Alimento

calculate_macros - Calcular Macronutrientes

calculate_meal_macros - Calcular Refeição Completa

Alimentos Customizados

add_custom_food - Adicionar Suplemento ou Marca

list_custom_foods - Listar Customizados

delete_custom_food - Remover Alimento

🎯 Exemplos de Uso

Diário Alimentar em Linguagem Natural

Adicionando Suplementos

🌐 Sistema de Apelidos (Aliases)

🎨 Arquitetura

Decisões de Design

📁 Estrutura do Projeto

🧪 Desenvolvimento

Executar Testes

Adicionar Aliases

Reconstruir Base de Dados

📋 Roadmap

📋 Licença

🪝 Agradecimentos

📞 Suporte

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`search_food` - Buscar Alimentos

`get_food` - Detalhes do Alimento

`calculate_macros` - Calcular Macronutrientes

`calculate_meal_macros` - Calcular Refeição Completa

`add_custom_food` - Adicionar Suplemento ou Marca

`list_custom_foods` - Listar Customizados

`delete_custom_food` - Remover Alimento

Packages