watsonx-medical-mcp-server by ruslanmv - MCP Server

🩺 Watsonx Medical MCP Server

A Python-based MCP “agent” that wraps IBM watsonx.ai to deliver conversational and medical-symptom analysis tools for watsonx Orchestrate.

🚀 Features

MCP protocol support over STDIO (ready for MCP Gateway auto-discovery)
Two production-ready tools
- chat_with_watsonx: general chat powered by watsonx.ai
- analyze_medical_symptoms: preliminary medical assessment
Conversation management helpers (get_conversation_summary, clear_conversation_history)
Resources & prompts for greetings, server info, and structured medical consultation
Zero-downtime dev reloads possible via uvicorn --reload (if you migrate to HTTP)
Makefile workflow for linting, formatting, testing, Docker, and more
Unit tests with pytest—CI-ready
Fully containerised with a lightweight Dockerfile

📦 Project Structure

watsonx-medical-mcp-server/
├── Makefile                  # Development workflow
├── Dockerfile                # Container image
├── requirements.txt          # Python deps
├── server.py                 # FastMCP stdio server
├── .env.example              # Copy to .env and set creds
├── test/
│   └── test_server.py        # Simple smoke test
├── docs/
│   └── README.md             # Simple user usage of frontend
└── README.md                 # You are here

⚙️ Prerequisites

Requirement	Notes
Python 3.11+	Local development
IBM watsonx.ai credentials	`API Key`, `Service URL`, `Project ID`
(Optional) Docker & GNU Make	Containerised workflows

🛠️ Setup & Local Development

Getting the server running locally is straightforward. This project requires Python 3.11.

Clone the Repository

git clone https://github.com/ruslanmv/watsonx-medical-mcp-server.git
cd watsonx-medical-mcp-server

Set Up the Environment Run the interactive setup command. It will create a virtual environment (.venv) and install all dependencies.
```
make setup
```
The script will detect if you have an existing environment and ask if you want to reuse or reinstall it.
Activate the Environment To run commands manually (like python server.py), you'll need to activate the environment in your shell.
```
source .venv/bin/activate
```
Note: You don't need to do this when using make targets like make run or make test, as they handle it automatically.

Configure Environment Variables Create a .env file from the example and add your IBM Watsonx credentials.

cp .env.example .env

Now, edit the .env file with your details:

# .env
WATSONX_APIKEY="your_api_key_here"
PROJECT_ID="your_project_id_here"

# Optional: Change the default model or URL
# WATSONX_URL="https://us-south.ml.cloud.ibm.com"
# MODEL_ID="meta-llama/llama-3-2-90b-vision-instruct"

Run the Server Start the server, which will communicate over STDIO (standard input/output).
```
make run
```
Run a Quick Test To confirm everything is working, run the test suite.
```
make test
```
This command will send a test query to your running server and verify the connection.
Run the Chatbot Application: In a second terminal, run the client application which provides the user interface.
```
python chatbot.py
```

Chatbot CLI Application: Or if you want something in the terminal run the client application via Terminal
```
python chatbot-cli.py
```

For more information click

⚙️ Makefile Targets

The Makefile provides several commands to streamline development. You can view this list anytime by running make help.

Makefile for watsonx-medical-mcp-server

Usage: make <target>

Core Targets:
  setup            - Interactively set up the Python virtual environment. The default target.
  reinstall        - Force re-creation of the virtual environment and install dependencies.
  run              - Run the MCP server.

Quality & Testing:
  lint             - Check code style with flake8.
  format           - Format code with black.
  check-format     - Check if code is formatted, without modifying files.
  test             - Run tests with pytest.
  check            - Run all checks: lint, check-format, and test.

Docker:
  docker-build     - Build the Docker image.
  docker-run       - Run the Docker container (requires .env file).

Cleanup:
  clean            - Remove the virtual environment and cache files.

🔗 Registering in MCP Gateway

Start MCP Gateway (e.g., docker compose up for the reference implementation).

Add the server

Via Admin UI

Navigate to Catalog → Servers → Add Server
Transport: STDIO
Command: /full/path/to/.venv/bin/python
Args: ["/full/path/to/server.py"]
Enable Auto-discover tools and save.

Via REST API

curl -X POST http://localhost:4444/servers \
  -H "Authorization: Bearer <ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "watsonx-medical-assistant",
    "transport": "stdio",
    "command": "/app/.venv/bin/python",
    "args": ["/app/server.py"],
    "autoDiscover": true
  }'

✅ Testing & Continuous Integration

Run tests locally
```
make test
```

Pre-commit hooks
```
pre-commit install
```

📜 License

Licensed under the Apache 2.0 license. See for full text.

Made with ❤️ and a dose of science to help users find reliable information—remember, this agent is not a substitute for professional medical advice.

ruslanmv/watsonx-medical-mcp-server

chat_with_watsonx

analyze_medical_symptoms