MCP-BOS

MCP-BOS is a modular, extensible MCP server framework designed for Claude Desktop integration. It automatically discovers modules placed under the modules directory and configures behavior through a global config.json. The server exposes functionality via a FastMCP-compatible interface, with modules encapsulating tools, resources, and prompts templates. You can enable or disable modules, adjust global settings like server_name and log_level, and customize module-specific parameters through the provided configuration, all without changing core code. To operate, run the main entry point (main.py) and let the framework initialize core components and load all available modules according to the config.

You can run MCP-BOS in multiple environments: directly with Python, or via uv for a smoother dev workflow. The framework is designed to auto-discover modules in the modules directory, so adding a new module is as simple as placing a properly structured Python package in that folder and enabling it in config.json. Claude Desktop integration is supported through the built-in CLI and mcp tooling, enabling you to install the server into Claude Desktop and expose its tools and resources for AI-assisted workflows. The server exposes tools via a decorator-based API on the module side, and resources via resource endpoints, all discoverable through the convention-based interface provided by the core module system.

Prerequisites:

• Python 3.8+ installed on your system
• Access to the internet to fetch dependencies
• Cloning or downloading the MCP-BOS repository

Step-by-step installation:

1. Clone the repository:

git clone https://github.com/kinbos/mcp-bos.git
cd mcp-bos

2. (Optional) Create and activate a virtual environment:

python -m venv venv
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

3. Install dependencies (the project uses the uv/mcp CLI for Python):

uv pip install mcp[cli]

4. Ensure the configuration file exists and is properly set up. The default config.json defines globals and module configurations; modify as needed.
5. Run the server:

python main.py

6. If you prefer development workflow with uv:

uv run main.py

7. To integrate with Claude Desktop, follow the CLI guidance in the repository to install and connect the server (e.g., using mcp install main.py).

Optional: Add new modules by creating a module directory under modules, exporting the module class in init.py, and enabling the module in config.json.

Tips and common considerations:

• The server auto-discovers modules in the modules directory; ensure each module exports a valid ModuleInterface implementation and is correctly referenced in config.json.
• Global and per-module configurations live in config.json. Use enabled: true/false to toggle modules and provide module-specific parameters as needed.
• Encoding: in Windows environments or mixed-language setups, set PYTHONIOENCODING to utf-8 to avoid encoding issues.
• Logging: configure log_level in global settings to control verbosity and aid debugging.
• Claude Desktop integration relies on the mcp CLI tooling; ensure the CLI is installed and the server is properly registered for Claude Desktop workflows.
• If a module fails to load, consult logs for the exact error (import errors, missing init.py exports, or misconfigured module interfaces are common causes).
• The transport option in global config often uses stdio; adjust if you need alternate transport layers.