Finizi B4B MCP Server

# Claude Desktop Setup Guide for Finizi B4B MCP Server ## Quick Setup (Copy & Paste) ### Step 1: Open Claude Desktop Configuration ```bash # On macOS open ~/Library/Application\ Support/Claude/claude_desktop_config.json # On Windows notepad %APPDATA%\Claude\claude_desktop_config.json # On Linux gedit ~/.config/Claude/claude_desktop_config.json ``` ### Step 2: Add This Configuration Copy and paste this into your `claude_desktop_config.json` file: ```json { "mcpServers": { "finizi-b4b": { "command": "uv", "args": [ "--directory", "/Users/trunghuynh/development/finizi-mcp", "run", "python", "-m", "finizi_b4b_mcp.server" ], "env": { "B4B_API_BASE_URL": "http://localhost:8000", "B4B_API_VERSION": "v1", "LOG_LEVEL": "INFO" } } } } ``` **Important:** If you have other MCP servers configured, merge this with your existing configuration: ```json { "mcpServers": { "your-existing-server": { ... }, "finizi-b4b": { "command": "uv", "args": [ "--directory", "/Users/trunghuynh/development/finizi-mcp", "run", "python", "-m", "finizi_b4b_mcp.server" ], "env": { "B4B_API_BASE_URL": "http://localhost:8000", "B4B_API_VERSION": "v1", "LOG_LEVEL": "INFO" } } } } ``` ### Step 3: Restart Claude Desktop **Important:** You MUST fully quit and restart Claude Desktop: - **macOS:** `Cmd + Q` or Right-click → Quit - **Windows:** Right-click system tray → Exit - **Linux:** `killall claude-desktop` then restart ### Step 4: Verify It's Working After restarting, you should see the MCP server icon in the bottom right of Claude Desktop. Try these commands: ``` You: "Login to B4B with phone +84909495665 and password Admin123@" Claude: ✓ Successfully logged in You: "List my entities" Claude: You have X entities... You: "Show me the available B4B tools" Claude: The Finizi B4B MCP server provides 15 tools... ``` --- ## Configuration Options ### For Production B4B API If you're connecting to a production API instead of localhost: ```json { "mcpServers": { "finizi-b4b": { "command": "uv", "args": [ "--directory", "/Users/trunghuynh/development/finizi-mcp", "run", "python", "-m", "finizi_b4b_mcp.server" ], "env": { "B4B_API_BASE_URL": "https://api.finizi.com", "B4B_API_VERSION": "v1", "LOG_LEVEL": "INFO", "API_TIMEOUT": "60" } } } } ``` ### Debug Mode For troubleshooting, enable debug logging: ```json { "mcpServers": { "finizi-b4b": { "command": "uv", "args": [ "--directory", "/Users/trunghuynh/development/finizi-mcp", "run", "python", "-m", "finizi_b4b_mcp.server" ], "env": { "B4B_API_BASE_URL": "http://localhost:8000", "B4B_API_VERSION": "v1", "LOG_LEVEL": "DEBUG" } } } } ``` --- ## Troubleshooting ### Problem: Server doesn't show up in Claude **Solution:** 1. Check the configuration file syntax (must be valid JSON) 2. Ensure path is correct: `/Users/trunghuynh/development/finizi-mcp` 3. Verify UV is installed: `which uv` 4. Check logs: `~/Library/Logs/Claude/mcp*.log` (macOS) ### Problem: "Command not found" error **Solution:** Install UV package manager: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` Then restart your terminal and Claude Desktop. ### Problem: Server crashes immediately **Solution:** 1. Test the server manually: ```bash cd /Users/trunghuynh/development/finizi-mcp uv run python -m finizi_b4b_mcp.server ``` 2. Check if dependencies are installed: ```bash uv sync ``` 3. Verify B4B API is accessible: ```bash curl http://localhost:8000/api/v1/ ``` ### Problem: "Not authenticated" errors **Solution:** You need to login first before using other tools: ``` "Login to B4B with phone +84909495665 and password Admin123@" ``` ### View Logs **macOS:** ```bash tail -f ~/Library/Logs/Claude/mcp-server-finizi-b4b.log ``` **Windows:** ```cmd type %APPDATA%\Claude\logs\mcp-server-finizi-b4b.log ``` --- ## Available Tools Once configured, you'll have access to these 15 tools: ### Authentication - `login` - Login with phone and password - `logout` - End your session - `whoami` - Get current user info ### Entities - `list_entities` - List your business entities - `get_entity` - Get entity details - `create_entity` - Create new entity - `update_entity` - Update entity info ### Invoices - `list_invoices` - List invoices with filters - `get_invoice` - Get invoice details - `import_invoice_xml` - Import XML invoice - `get_invoice_statistics` - Get analytics ### Vendors - `list_vendors` - List vendors - `get_vendor` - Get vendor details ### Products - `list_products` - List products - `search_similar_products` - Find similar products --- ## Example Conversations ### Basic Workflow ``` You: "Login to B4B with phone +84909495665 and password Admin123@" Claude: ✓ Successfully logged in You: "Show me all my entities" Claude: You have 2 entities: 1. ABC Company (Tax ID: 0123456789) 2. XYZ Corp (Tax ID: 9876543210) You: "List invoices for ABC Company from January 2025" Claude: Found 15 invoices for January 2025... You: "Show me invoice statistics for 2025" Claude: Invoice Statistics for 2025: - Total Invoices: 150 - Total Amount: 5,000,000 VND - Average Invoice: 33,333 VND ... ``` ### Advanced Usage ``` You: "Create a new company entity named 'Tech Innovations' with tax ID 1234567890" Claude: ✓ Created entity: Tech Innovations (ID: xxx-xxx-xxx) You: "Import this XML invoice for Tech Innovations: [paste XML]" Claude: ✓ Invoice imported successfully (Invoice #: INV-2025-001) You: "Find products similar to 'MacBook Pro' in Tech Innovations" Claude: Found 5 similar products: 1. MacBook Air M2 (95% match) 2. Dell XPS 15 (87% match) ... ``` --- ## Next Steps 1. ✅ Configure Claude Desktop (steps above) 2. ✅ Restart Claude Desktop 3. ✅ Test login command 4. ✅ Explore the 15 available tools 5. 📖 Read the full [README.md](README.md) for more details --- ## Support - **Documentation:** [README.md](README.md) - **API Reference:** [docs/API_MAPPING.md](docs/API_MAPPING.md) - **Development Guide:** [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - **MCP Specification:** https://modelcontextprotocol.io **You're all set!** The Finizi B4B MCP Server is now ready to use with Claude Desktop. 🎉