Content
# Bobbeori MCP Server
Connect Bobbeori food-management tools to ChatGPT, Codex, Claude, and other MCP clients with OAuth and preview-first write actions.
## What you can do
- View refrigerator inventory and expiring ingredients.
- Recommend recipes from ingredients you already have.
- Look up food storage, handling, and nutrition guidance.
- Preview and save shopping lists.
- Preview and stock reviewed receipt items.
- Preview and create Google Calendar events or reminders.
## Quick start
```bash
git clone https://github.com/Bobbeori/bobbeori-mcp-server.git
cd bobbeori-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
uvicorn bobbeori_mcp.server:app --host 0.0.0.0 --port 8001
```
Windows PowerShell:
```powershell
git clone https://github.com/Bobbeori/bobbeori-mcp-server.git
cd bobbeori-mcp-server
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
copy .env.example .env
uvicorn bobbeori_mcp.server:app --host 0.0.0.0 --port 8001
```
Docker:
```bash
docker build -t bobbeori-mcp-server .
docker run --env-file .env -p 8001:8001 bobbeori-mcp-server
```
## Connect an MCP client
Production MCP URL:
```text
https://mcp.bobbeori.com/mcp
```
OAuth resource:
```text
https://mcp.bobbeori.com
```
Codex CLI:
```powershell
codex mcp add bobbeori `
--url https://mcp.bobbeori.com/mcp `
--oauth-client-id 3nu2uqh1ir8d10ljocufuj2qv1 `
--oauth-resource https://mcp.bobbeori.com
codex mcp login bobbeori --scopes bobbeori-mcp/inventory.read,bobbeori-mcp/recipe.read,bobbeori-mcp/guide.read,bobbeori-mcp/receipt.write,bobbeori-mcp/shopping.write,bobbeori-mcp/calendar.write
```
Claude Desktop-style remote server config:
```json
{
"mcpServers": {
"bobbeori": {
"url": "https://mcp.bobbeori.com/mcp"
}
}
}
```
For ChatGPT, create a connector/plugin with:
```text
MCP Server URL: https://mcp.bobbeori.com/mcp
Authentication: OAuth
Resource: https://mcp.bobbeori.com
```
## Example prompts
- "Show my Bobbeori refrigerator ingredients that expire this week."
- "Recommend dinner recipes using ingredients I already have."
- "Preview adding these receipt items to my refrigerator."
- "Create a shopping list for missing ingredients from recipe 175."
- "Preview a calendar reminder to use tofu tomorrow at 9 AM KST."
## Tools
| Tool | Purpose | Scope |
|---|---|---|
| `inventory.list` | List refrigerator items | `bobbeori-mcp/inventory.read` |
| `inventory.expiring` | List expiring or expired items | `bobbeori-mcp/inventory.read` |
| `recipe.recommend` | Recommend recipes | `bobbeori-mcp/recipe.read` |
| `recipe.get` | Get recipe details | `bobbeori-mcp/recipe.read` |
| `ingredient.guide` | Get food storage and nutrition guidance | `bobbeori-mcp/guide.read` |
| `receipt.preview` | Preview stocking receipt items | `bobbeori-mcp/receipt.write` |
| `receipt.commit` | Commit a receipt preview | `bobbeori-mcp/receipt.write` |
| `shopping.preview` | Preview a shopping list | `bobbeori-mcp/shopping.write` |
| `shopping.save` | Save a shopping list preview | `bobbeori-mcp/shopping.write` |
| `calendar.preview` | Preview a calendar event | `bobbeori-mcp/calendar.write` |
| `calendar.create` | Create a calendar event preview | `bobbeori-mcp/calendar.write` |
| `reminder.preview` | Preview a reminder | `bobbeori-mcp/calendar.write` |
| `reminder.create` | Create a reminder preview | `bobbeori-mcp/calendar.write` |
## Write safety
Bobbeori write tools are preview-first.
1. Call the matching `*.preview` tool.
2. Show the preview and warnings to the user.
3. Ask for explicit confirmation.
4. Pass the returned `confirmation_token` unchanged to `*.commit`, `*.save`, or `*.create`.
Never invent a `user_id`; OAuth supplies the account.
## Environment
Required production values:
```env
BOBBEORI_API_BASE_URL=https://api.bobbeori.com
BOBBEORI_MCP_API_PREFIX=/api/v1/mcp
MCP_ISSUER_URL=
MCP_RESOURCE_URL=https://mcp.bobbeori.com
MCP_JWKS_URL=
MCP_JWT_AUDIENCE=https://mcp.bobbeori.com
MCP_PREVIEW_TOKEN_SECRET=
```
See [.env.example](.env.example) for all options.
## Smoke test
```powershell
$env:MCP_ACCESS_TOKEN="<oauth-access-token>"
py scripts/test_mcp_oauth.py `
--mcp-url https://mcp.bobbeori.com/mcp `
--resource-url https://mcp.bobbeori.com
```
## Development
```bash
pip install -e .
pytest -q
```
This repository owns the external MCP boundary. Product logic, OCR, database access, recipe search, shopping persistence, and calendar persistence live in the main Bobbeori backend.
See [docs/bridge-api.md](docs/bridge-api.md) for the backend bridge contract.
## Security
See [SECURITY.md](SECURITY.md). Do not put OAuth client secrets, API keys, user receipt data, or production `.env` files in this repository.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
MIT. See [LICENSE](LICENSE).
