medifinder-mcp

Message Communication Protocol (MCP) server that facilitates secure, standardized communication between system components and the medicine inventory database. Provides RESTful endpoints for location-based medicine searches, availability queries, and optimized messaging for WhatsApp integration.

0 stars PythonSearch & Data Retrieval Updated Mar 22, 2025

Documentation

MedifinderMCP Server

An MCP (Model Context Protocol) server for medicine inventory queries, designed to work with AI assistants like Claude.

Overview

The MedifinderMCP Server provides tools and resources for querying a medicine inventory database through the Model Context Protocol (MCP). It allows AI assistants and other clients to:

Search for medicines by name or location
Check medicine availability at different healthcare facilities
Get stock information for specific medicines
View statistics on medicine availability by region
Analyze stock status across the healthcare system

Database Schema

The application uses a normalized database schema:

code

Region
  - region_id (PK)
  - name
  - code
  - created_at
  - updated_at

MedicalCenter
  - center_id (PK)
  - code
  - name
  - region_id (FK -> Region)
  - category
  - reporter_name
  - institution_type
  - reporter_type
  - address
  - latitude
  - longitude
  - created_at
  - updated_at

ProductType
  - type_id (PK)
  - code
  - name
  - description
  - created_at
  - updated_at

Product
  - product_id (PK)
  - code
  - name
  - type_id (FK -> ProductType)
  - description
  - dosage_form
  - strength
  - created_at
  - updated_at

Inventory
  - inventory_id (PK)
  - center_id (FK -> MedicalCenter)
  - product_id (FK -> Product)
  - current_stock
  - avg_monthly_consumption
  - accumulated_consumption_4m
  - measurement
  - last_month_consumption
  - last_month_stock
  - status_indicator
  - cpma_12_months_ago
  - cpma_24_months_ago
  - cpma_36_months_ago
  - accumulated_consumption_12m
  - report_date
  - status
  - created_at
  - updated_at

User
  - user_id (PK)
  - phone_number
  - name
  - preferred_location
  - created_at
  - updated_at

SearchHistory
  - search_id (PK)
  - user_id (FK -> User)
  - product_query
  - location_query
  - search_radius
  - results_count
  - created_at

Project Structure

code

medifinder-mcp/
├── app/
│   ├── __init__.py
│   ├── config.py            # Configuration management
│   ├── db/
│   │   ├── __init__.py
│   │   ├── connection.py    # Database connection handling
│   │   └── queries.py       # SQL queries
│   ├── models/
│   │   ├── __init__.py
│   │   ├── base.py          # Base model with timestamp fields
│   │   ├── region.py        # Region model
│   │   ├── medical_center.py # Medical center model
│   │   ├── product_type.py  # Product type model
│   │   ├── product.py       # Product model
│   │   ├── inventory.py     # Inventory model
│   │   ├── user.py          # User model
│   │   └── search_history.py # Search history model
│   ├── mcp/
│   │   ├── __init__.py
│   │   ├── server.py        # MCP server setup
│   │   ├── tools.py         # Tool implementations
│   │   ├── resources.py     # Resource implementations
│   │   └── prompts.py       # Prompt templates
│   └── utils/
│       ├── __init__.py
│       └── helpers.py       # Helper functions
├── main.py                  # Application entry point
├── requirements.txt         # Dependencies
└── README.md                # Documentation

MCP Features

Tools

`search_medicines`: Search for medicines by name or location
`get_medicine_locations`: Find locations where a medicine is available
`get_medicine_stock`: Get stock information for a specific medicine
`get_regional_statistics`: Get medicine statistics by region
`get_medicine_status`: Get overall medicine statistics
`diagnose_database`: Check database connectivity and content
`troubleshoot_connection`: Detailed database connection diagnostics
`create_database_schema`: Create database tables based on models

Resources

`product://{id}`: Get product details by ID
`stock://{name}`: Get stock information for a product by name
`locations://{region}`: Get medical centers in a specific region
`statistics://stock`: Get overall stock statistics
`statistics://regions`: Get regional statistics

Prompts

`medicine_search_prompt`: Template for searching medicines by name
`medicine_availability_prompt`: Template for checking medicine availability
`medicine_statistics_prompt`: Template for analyzing medicine statistics
`regional_availability_prompt`: Template for analyzing regional medicine availability

Installation

1. Clone the repository:

code

git clone https://github.com/yourusername/medifinder-mcp.git
   cd medifinder-mcp

2. Create a virtual environment and install dependencies:

code

python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. Set up environment variables by creating a `.env` file:

code

DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=medifinderbot
   DB_USER=your_user
   DB_PASSWORD=your_password
   DEBUG=True
   ENV=development
   SERVER_NAME=MedifinderMCP
   SERVER_VERSION=1.0.0
   MCP_SERVER_NAME=MedifinderMCP
   MCP_SERVER_DESCRIPTION=MCP server for medicine inventory queries
   MAX_SEARCH_RESULTS=50
   SEARCH_SIMILARITY_THRESHOLD=0.3

4. Create the database:

code

# Connect to PostgreSQL
   psql -U postgres
   
   # Create database and user
   CREATE DATABASE medifinderbot;
   CREATE USER your_user WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE medifinderbot TO your_user;
   
   # Exit PostgreSQL
   \q

5. Initialize the database schema:

After starting the server, use the `create_database_schema` tool to create the tables.

Usage

Running the Server Locally

You can run the MCP server directly:

code

python main.py

Using MCP Inspector

For development and testing, the MCP Inspector provides a convenient way to interact with the server:

1. Install MCP CLI:

code

pip install mcp[cli]

2. Run the server in development mode:

code

python -m mcp dev main.py

3. The MCP Inspector will open in your browser, allowing you to:

Integration with Claude Desktop

To use the server with Claude Desktop:

1. Create a batch file for reliable startup (run-mcp-server.bat):

batch

@echo off
   cd /d %~dp0
   call venv\Scripts\activate.bat
   python main.py

2. Install the server in Claude Desktop:

code

mcp install run-mcp-server.bat -f .env

3. Alternatively, edit Claude Desktop's config file manually:

json

{
     "mcpServers": {
       "MedifinderMCP": {
         "command": "C:\\path\\to\\project\\venv\\Scripts\\python.exe",
         "args": ["C:\\path\\to\\project\\main.py"],
         "env": {
           "DB_HOST": "localhost",
           "DB_PORT": "5432",
           "DB_NAME": "medifinderbot",
           "DB_USER": "your_user",
           "DB_PASSWORD": "your_password",
           "DEBUG": "True",
           "ENV": "development",
           "SERVER_NAME": "MedifinderMCP",
           "SERVER_VERSION": "1.0.0",
           "MCP_SERVER_NAME": "MedifinderMCP",
           "MCP_SERVER_DESCRIPTION": "MCP server for medicine inventory queries",
           "MAX_SEARCH_RESULTS": "50",
           "SEARCH_SIMILARITY_THRESHOLD": "0.3"
         }
       }
     }
   }

4. In Claude Desktop, select the MedifinderMCP server from the servers dropdown to enable it for your conversation.

Troubleshooting

Common Issues

1. Database Connection Issues:

2. Missing Tables:

3. Empty Results:

4. Session Binding Errors:

5. Missing Dependencies:

Diagnostic Tools

When troubleshooting, use these built-in diagnostic tools:

1. `diagnose_database`: Checks if:

2. `troubleshoot_connection`: Provides detailed information about:

3. `create_database_schema`: Creates the database tables and provides:

License

MIT License

Contributors

Lenin Carrasco - Initial work

Frequently asked questions

What is medifinder-mcp?

medifinder-mcp is Message Communication Protocol (MCP) server that facilitates secure, standardized communication between system components and the medicine inventory database. Provides RESTful endpoints for location-based medicine searches, availability queries, and optimized messaging for WhatsApp integration.

How do I install medifinder-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is medifinder-mcp open source?

Yes — it is hosted on GitHub at https://github.com/MediFinderBot/medifinder-mcp.

Related MCP tools

openhands

🙌 OpenHands: Code Less, Make More for the Model Context Protocol. Enhance AI assistants with powerful integrations. Python-based implementation.

64,677 Python

agentartificial-intelligencechatgpt+6

mem0

Universal memory layer for AI Agents; Announcing OpenMemory MCP - local and secure memory management. Python-based implementation.

42,646 Python

agentsaiai-agents+12

chatgpt-on-wechat

基于大模型搭建的聊天机器人，同时支持微信公众号、企业微信应用、飞书、钉钉等接入，可选择ChatGPT/Claude/DeepSeek/文心一言/讯飞星火/通义千问/ Gemini/GLM-4/Kimi/LinkAI，能处理文本、语音和图片，访问操作系统和互联网，支持基于自有知识库进行定制企业智能客服。

39,573 Python

aiai-agentchatgpt+17

gpt-researcher

An LLM agent that conducts deep research (local and web) on any given topic and generates a long report with citations. Built for the Model Context Protocol to

24,026 Python

agentaiautomation+8

fastmcp

🚀 The fast, Pythonic way to build MCP servers and clients Trusted by 19900+ developers. Trusted by 19900+ developers. Trusted by 19900+ developers.

19,927 Python

agentsfastmcpllms+6

maxkb

🔥 MaxKB is an open-source platform for building enterprise-grade agents. MaxKB 是强大易用的开源企业级智能体平台。 for the Model Context Protocol. Enhance AI assistants with po

19,062 Python

agentagentic-aichatbot+11

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP