For Apache Ofbiz
A Model Context Protocol (MCP) server platform for Apache OFBiz
Ask AI about For Apache Ofbiz
Powered by Claude ยท Grounded in docs
I know everything about For Apache Ofbiz. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Server for Apache OFBizยฎ
This project provides an implementation of a Model Context Protocol (MCP) server that runs custom tools to invoke remote services thorugh API endpoints, based on requests from an MCP client (usually hosted in a generative AI application such as Claude Desktop).
The project is implemented with the Anthropic TypeScript SDK, and requires Node.js as runtime environment.
By leveraging the sample configuration and tool files contained in the examples folder, the MCP server can be easly configured, e.g., to point to specific backend systems and to use OAuth2.0 authorization flows, and new tools can be developed to address specific use cases.
In short, this project can be used as a platform to implement your own tools and enable generative AI applications to interact with any backend system that exposes API endpoints, such as Apache OFBizยฎ or Moqui.
This software is licensed under the Apache License, Version 2.0.
Apache OFBizยฎ is a trademark of the Apache Software Foundation.
Table of Contents
- Quick-start guide
- Features
- Configuration
- Project Structure
- Build the Project
- Test the Remote MCP Server
- Inspect the MCP server
- Containerization with Docker
Quick-start guide
> git clone https://github.com/jacopoc/mcp-server-for-apache-ofbiz.git mcp-server
> cd mcp-server
mcp-server> npm install
mcp-server> cd examples/tools
mcp-server/examples/tools> npm install
mcp-server/examples/tools> npm run build
mcp-server/examples/tools> cd ..
mcp-server/examples> ./update_token.sh admin ofbiz
mcp-server/examples> cd ..
mcp-server> node build/server.js ./examples/config ./examples/tools
From another shell you can start the MCP Inspector:
> npx @modelcontextprotocol/inspector
This command will open a browser window to the Inspector application: set Transport Type to Streamable HTTP and URL to http://localhost:3000/mcp and hit the Connect button. After that, you will be connected to the MCP server and could execute its tool, that fetches data from one of the public demo instances of Apache OFBiz.
Features
The MCP server communicates with the MCP client via MCP Streamable HTTP transport.
The server dynamically discovers custom tools contained in a directory, whose path is specified as a command-line argument when the server is lauched.
The tools are defined and implemented in their own files. For example, the sample tool examples/tools/src/findProductById.ts invokes an endpoint in Apache OFBiz to retrieve product information for a given product ID. This works with an out-of-the-box (OOTB) OFBiz instance with the rest-api plugin installed.
The server:
- is compliant with the latest MCP specifications (2025-11-25)
- supports authorization according to the MCP recommendations (OAuth Authorization Code Flow with support for Metadata discovery, dynamically registered clients, etc...)
- supports the token exchange OAuth flow in order to obtain a valid token for the backend system
- performs token validation with configurable scopes and audience verification
- supports TLS connections (https) for secure, encrypted communications over public networks
- provides rate limiting features to protect the MCP server and the backend server from denial of service attacks
- allows CORS restriction to enable secure interactions with trusted front-end applications
- supports hosts and origins restrictions for DNS rebinding protection, useful when the server is deployed as a local application
Configuration
Server configuration is managed via the config.json file contained in a configuration directory, whose path is specified as a command-line argument when the server is lauched:
SERVER_PORTโ the port on which the MCP server listens for client connections (required only for the remote server)TLS_CERT_PATHโ path to the file containing the certificate for TLS, either absolute or relative to the configuration folderTLS_KEY_PATHโ path to the file containing the private key for TLS, either absolute or relative to the configuration folderTLS_KEY_PASSPHRASEโ (optional) passphrase for theTLS_KEY_PATHfileMCP_SERVER_CORS_ORIGINSโ CORS origin allowedMCP_SERVER_DNS_REBINDING_PROTECTION_ALLOWED_HOSTS- list of allowed values for request headerHostfor DNS rebinding protectionMCP_SERVER_DNS_REBINDING_PROTECTION_ALLOWED_ORIGINS- list of allowed values for request headerOriginfor DNS rebinding protectionRATE_LIMIT_WINDOW_MSโ time window in ms for the requests rate limiting featureRATE_LIMIT_MAX_REQUESTSโ max number of requests allowed in the time windowMCP_SERVER_BASE_URLโ the base URL of the MCP server used to get OAuth metadata (Protected Resource Server in OAuth)AUTHZ_SERVER_BASE_URLโ the base URL of the Authorization (Authz) server (OAuth)SCOPES_SUPPORTEDโ the scopes that the MCP client can requestBACKEND_API_BASEโ the base URL for backend REST API callsBACKEND_USER_AGENTโ the user agent set in the header of downstream API callsMCP_SERVER_CLIENT_IDโ Client ID, as registered in Authz server. It is used by the MCP server to validate the "aud" claim of tokens received by clients. If not set or empty, no "aud" claim validation is performed. This parameter is also required for token exchangeMCP_SERVER_CLIENT_SECRETโ the secret associated withMCP_SERVER_CLIENT_IDBACKEND_API_AUDIENCEโ the OAuth audience paramenter for the backend systemBACKEND_API_RESOURCEโ the OAuth resource parameter for the backend systemTOKEN_EXCHANGE_SCOPEโ the list of scopes requested in the token exchangeBACKEND_API_AUTH- the URL to get the OFBiz APIs access token used if token exchange is not enabledBACKEND_AUTH_TOKENโ the token to authorize backend API calls used if token exchange is not enabled
If both TLS_CERT_PATH and TLS_KEY_PATH are configured, the MCP server will operate over HTTPS; otherwise, it falls back to HTTP.
If either MCP_SERVER_BASE_URL or AUTHZ_SERVER_BASE_URL are not set, authorization is disabled and the MCP server is publicly accessible.
If authorization is enabled, but either MCP_SERVER_CLIENT_ID or MCP_SERVER_CLIENT_SECRET are not set, token exchange is disabled.
If token exchange is not enabled, the access token for the back-end APIs can be set in BACKEND_AUTH_TOKEN.
Project Structure
mcp-server-for-apache-ofbiz/
โโโ examples/
โ โโโ config/
โ | โโโ config.json # Sample server configuration file
โ โโโ tools/
โ | โโโ src/ # Authorization modules
โ โ โ โโโ findProductById.ts # Sample tool calling an Apache OFBiz endpoint
โ โ โโโ package.json
โ โ โโโ tsconfig.json
โ โโโ update_token.sh # Script to get a backend auth token for Apache OFBiz APIs
โ โโโ README.md
โโโ src/
โ โโโ lib/ # Internal modules of the MCP server:
โ | โโโ auth/* # Authorization modules
โ | โโโ config/* # Configuration modules
โ | โโโ mcp/* # MCP specific modules
โ | โโโ app.ts # Module for the Express app setup
โ | โโโ server-factory.ts # Module for the HTTP server setup
โ โโโ server.ts # MCP server
โโโ package.json
โโโ tsconfig.json
โโโ README.md # This readme file
โโโ LICENSE # Apache License, Version 2.0
Build the Project
npm install
npm run build
Test the MCP Server
With the configuration file provided (./examples/config/config.json) the MCP server operates over a plain HTTP connection, on port 3000, with authorization and token exchange disabled, and invokes the APIs of one of the Apache OFBiz demo instances.
The access token required for the OFBiz APIs can be generated and set in BACKEND_AUTH_TOKEN by running from the examples folder the utility script
update_token.sh <user> <password>
with, e.g., admin and ofbiz, as user and password, respectively.
This script retrieves a JWT for an OOTB OFBiz instance from https://demo-stable.ofbiz.apache.org/rest/auth/token, as specified in BACKEND_API_AUTH.
In order to compile the sample tool, go to the examples/tools directory and run
npm install
npm run build
Start the server from the main folder, specifying the paths to the examples configuration and tools folders:
node ./build/server.js ./examples/config ./examples/tools
The server is reachable at http://localhost:3000/mcp.
You can test the MCP server with the free version of Claude Desktop.
Edit or create the Claude Desktop configuration file:
~/Library/Application\ Support/Claude/claude_desktop_config.json
Add your MCP server configuration:
{
"mcpServers": {
"Apache OFBiz": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3000/mcp", "--allow-http"]
}
}
}
After updating the configuration file, launch Claude Desktop and try the following sample prompts:
- "Can you provide some information about the product WG-1111?"
- "Create a SEO friendly description for the product with ID GZ-1000"
- "Can you provide some information about a product?"
(Claude will ask for a product ID before invoking the tool.) - "Can you compare two products?"
(Claude will ask for two product IDs, invoke the tool twice, and then compare the results.)
Inspect the MCP server
You can use Anthropicโs Inspector to easily test interactions with the MCP server.
Run (and install) the Inspector with:
npx @modelcontextprotocol/inspector
This will open a browser window ready to test your MCP servers.
Containerization with Docker
The following instructions describe how to containerize the MCP server using Docker and the Dockerfile provided.
First, build a Docker image named, e.g., mcp4ofbiz-image, by running the following command from the project's home directory:
docker build -t mcp4ofbiz-image .
If your target environment uses a different CPU architecture than your development machine (for example, if you're working on an Apple M1 but deploying to an amd64 platform), make sure to build the image for the correct target architecture:
docker build --platform=linux/amd64 -t mcp4ofbiz-image .
After building the image, create a container, e.g., named mcp4ofbiz-container
docker create --name mcp4ofbiz-container -p 3000:3000 -v ./examples/config:/config -v ./examples/tools:/tools mcp4ofbiz-image
and run it
docker start mcp4ofbiz-container
The MCP server will be available at http://localhost:3000/mcp.
If you wish, you can push the image to your registry by running
docker push myregistry.com/mcp4ofbiz-image
