Finizi B4B

You can connect your AI assistant to Finizi B4B through this MCP server to manage entities, invoices, vendors, and products using natural language commands. It handles authentication, token management, retries, and structured responses so you can focus on building conversational workflows.

How to use

Use an MCP client to call the available tools. Authenticate once per session with login, then use subsequent calls such as list_entities, get_entity, list_invoices, or search_similar_products to perform tasks like finding a company, viewing an invoice, or locating similar products. The server automatically passes your JWT token to Finizi B4B API and returns structured results that you can render in your assistant.

How to install

Prerequisites you need before installing: Python 3.11 or higher, and either the UV package manager or pip for installation.

# Using UV (recommended)
git clone https://github.com/finizi/finizi-mcp.git
cd finizi-mcp

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install the MCP locally
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e "."

Configuration and environment

Configure the environment with your Finizi B4B API details. Create a local environment file and set the API URL, version, timeouts, and retry behavior used by the MCP server.

# Example environment file content
B4B_API_BASE_URL=https://api.finizi.com
B4B_API_VERSION=v1
API_TIMEOUT=30
API_CONNECT_TIMEOUT=10
MAX_RETRIES=3
LOG_LEVEL=INFO

Run the MCP server locally

Start the MCP server using a Python invocation that runs the server entry point. You provide the path to the server script and necessary environment variables.

# Start the server (example)
python /path/to/finizi-mcp/run_server.py

Claude Desktop configuration (example)

If you use Claude Desktop to interact with the MCP server, configure it to run the local server with the appropriate environment variable. The following example shows how to point Claude Desktop to your local run script and set the B4B API base URL.

{
  "mcpServers": {
    "finizi_b4b": {
      "command": "python",
      "args": ["/path/to/finizi-mcp/run_server.py"],
      "env": {
        "B4B_API_BASE_URL": "https://api.finizi.com"
      }
    }
  }
}

Available tools

login

Authenticate users with phone and password to obtain a JWT token for subsequent API calls.

logout

Clear the authentication session and revoke the current token.

whoami

Return information about the currently authenticated user.

list_entities

List business entities with pagination and search filters.

get_entity

Retrieve detailed information for a specific entity.

create_entity

Create a new business entity with provided details.

update_entity

Update details of an existing entity.

list_invoices

List invoices with filters such as date range and status.

get_invoice

Retrieve detailed information for a specific invoice.

import_invoice_xml

Import an invoice from an XML string.

get_invoice_statistics

Get analytics and statistics for invoices within a date range.

list_vendors

List vendors with pagination and search.

get_vendor

Retrieve detailed information for a specific vendor.

list_products

List products with optional category and search filters.

search_similar_products

Find similar products using AI matching.