modular-mcp

Modular MCP server with Odoo-style addons (__manifest__.toml) plus an optional FastAPI web layer.

Setup

python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
copy .env.example .env

Configuration is primarily in config.toml. Environment variables still override FastAPI settings (.env supported).

Relative paths inside a config file (addons_paths, log_dir, data_file) resolve from the directory of that config file, not from the package install root.

Tool-specific settings (timeout, retries, …) belong in each addon's config.toml, not the host profile. Host [logging.addons.<log_key>] only overrides addon logging when needed.

Related MCP server: mcp-app

Run

modular-mcp serve
modular-mcp mcp serve
modular-mcp get hello

# External profile (separate config + addon paths)
modular-mcp --config /path/to/profile/config.toml mcp serve

• FastAPI UI: http://127.0.0.1:8000/

• MCP default: streamable-http on http://127.0.0.1:5001 (see config.toml)

Addons

Each addon is a folder under addons/ with:

addons/my_addon/
  __manifest__.toml
  config.toml
  tools.py          # register_tools(mcp, config, logger)

Sample addon: addons/key_value_store/ with kv_get / kv_set.

Shared imports inside addons:

from app.mcp.utils import format_json, exception_to_error_response
from app.mcp.logging import monitor_performance
from helpers import my_helper  # local module in the same addon folder

Port external tools into an addon

# Before (standalone tool module)
tools/my_tool.py

# After
addons/my_tool/
  __manifest__.toml
  config.toml
  tools.py

Move the tool code into tools.py, change shared imports to app.mcp.utils / app.mcp.logging, and set log_key in __manifest__.toml.

Test & lint

pytest
ruff check .
ruff format --check .
mypy
pyright

Pre-commit

pip install -e ".[dev]"
pre-commit install
pre-commit run --all-files