Connects to a PostgreSQL database (with TimescaleDB extension) to compute and retrieve factory KPIs.
Provides KPI tools (Productivity, Quality, Downtime, Alarms) for Factory Intelligence by querying a TimescaleDB database.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Factory Intelligence MCP Server Get the KPI summary for today's production shift."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is a production-ready MCP (Model Context Protocol) server providing KPI tools for a Factory Intelligence dashboard. It communicates via the Stdio transport and leverages TimescaleDB for efficient time-series analysis, calculating Productivity, Quality, Downtime metrics, and diagnosing Alarms.
Productivity KPI (get_productivity_kpi): Computes production efficiency against targets.
Quality KPI (get_quality_kpi): Calculates Yield % and Defect Rate %.
Downtime KPI (get_downtime_kpi): Analyzes machine availability based on production gaps.
KPI Summary (get_kpi_summary): Bundles all metrics for high-level dashboards.
Downtime Alarms Analysis (get_downtime_alarms_analysis): Correlates alarms with downtime periods to identify root causes.
Related MCP server: TimescaleDB MCP Server
Python 3.10+
uv (recommended) or pip
A running PostgreSQL/TimescaleDB instance with the factory schema.
git clone https://github.com/lvshrd/Factory-Intelligence-MCP-Server.git
cd Factory-Intelligence-MCP-Server
uv sync # Installs dependencies including mcp, psycopg2, python-dateutilThe server requires a DATABASE_URL environment variable. You have two options:
Option A: .env file (Recommended for local dev)
Create a .env file in the Factory-Intelligence-MCP-Server directory:
DATABASE_URL="postgresql://username:password@localhost:5432/ProductionDB"Option B: Environment Variable Injection
Pass the DATABASE_URL directly through your MCP client configuration (see below).
You can configure this server in Claude Desktop or Cursor's MCP settings.
Add this to your claude_desktop_config.json (or Cursor's MCP settings):
{
"mcpServers": {
"factory-intelligence": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/Factory-Intelligence-MCP-Server",
"run",
"server.py"
],
"env": {
"DATABASE_URL": "postgresql://username:password@localhost:5432/ProductionDB"
}
}
}
}To integrate this server programmatically using the official LangChain MCP client:
from langchain_mcp_adapters.client import MultiServerMCPClient
# Initialize client with Stdio transport
client = MultiServerMCPClient(
{
"factory-intelligence": {
"transport": "stdio",
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/Factory-Intelligence-MCP-Server",
"run",
"server.py"
],
"env": {
"DATABASE_URL": "postgresql://username:password@localhost:5432/ProductionDB"
}
}
}
)All tools share a common input structure requiring start_time and end_time.
get_productivity_kpiComputes productivity metrics based on total good and bad bottles produced versus a target.
Inputs:
start_time (string, ISO 8601)
end_time (string, ISO 8601)
Outputs:
summary: Object containing value (ratio), total_production, good_count, bad_count.
timeseries: Array of { timestamp, value } objects.
metadata: Info on data source and computation notes.
get_quality_kpiComputes Quality (Yield %) and Defect Rate %.
Inputs: start_time, end_time (ISO 8601)
Outputs:
summary: yield_percentage, defect_rate_percentage.
timeseries: Trend of Yield % over time.
get_downtime_kpiCalculates uptime and downtime duration based on production gaps (zero production intervals).
Inputs: start_time, end_time (ISO 8601)
Outputs:
summary: uptime_seconds, downtime_seconds, availability_percentage.
get_kpi_summaryBundles Productivity, Quality, and Downtime KPIs into a single response.
Inputs: start_time, end_time (ISO 8601)
Outputs:
productivity: Summary object from Tool 1.
quality: Summary object from Tool 2.
downtime: Summary object from Tool 3.
get_downtime_alarms_analysisIdentifies and ranks alarms that were active during inferred downtime periods.
Inputs: start_time, end_time (ISO 8601)
Outputs:
summary: Total downtime events and top alarm count.
top_alarms: List of alarms with frequency and total_duration_during_downtime.
downtime_events_sample: List of specific downtime windows (start, end, duration).
Below is a demonstration of an AI agent (Cursor) calling the tools to analyze productivity and downtime root causes:
Calling get_productivity_kpi for a single day:
{
"name": "get_productivity_kpi",
"arguments": {
"start_time": "2025-12-10T00:00:00Z",
"end_time": "2025-12-10T23:59:59Z"
}
}Note: The result field contains the actual tool payload.
{
"tool": "get_productivity_kpi",
"inputs": {
"start_time": "2025-12-10T00:00:00Z",
"end_time": "2025-12-10T23:59:59Z"
},
"result": {
"summary": {
"kpi_name": "Productivity",
"value": 0.2019,
"total_production": 54074.0,
"good_count": 53473.0,
"bad_count": 601.0,
"unit": "ratio"
},
"timeseries": [
{
"timestamp": "2025-12-10T00:00:00+00:00",
"value": 54074.0
}
],
"metadata": {
"data_source": "agg_counter_1hour",
"bucket_width": "1 day",
"computation_note": "Target based on max observed speed (11160 BPH)"
}
},
"status": "ok",
"errors": []
}agg_counter_10sec_delta (The Source of Truth): Used for precise logic like Downtime Inference. Its delta-based structure allows us to accurately determine "zero production" intervals at a high resolution (10 seconds).
agg_counter_1min / agg_counter_1hour (Performance): Used for KPI calculations over longer time ranges. Querying pre-aggregated data reduces the number of rows scanned by orders of magnitude (e.g., 1 year of 1-hour data is ~8,760 rows, vs ~3.1 million rows for 10-second data).
agg_boolean_state_durations: Used for Alarm analysis because it natively stores state intervals (start, end, value), making overlap queries significantly easier than reconstructing states from raw timeseries events.
Downtime Inference: We assume Zero Production = Downtime. Any 10-second bucket with sum(delta) = 0 is treated as a stop.
Target Production: Calculated dynamically using a "Design Speed" of 11,160 Bottles Per Hour. This rate was derived from analyzing the historical data to find the maximum observed production in a single 10-second interval (31 bottles), ensuring the productivity ratio is relative to the machine's demonstrated peak capacity.
Alarm Correlation: We assume that if an alarm is active (value=true) and its time interval overlaps with a downtime event, it is related to that downtime.
Dynamic Aggregation Strategy: The system implements an intelligent router (get_aggregation_strategy) that selects the optimal table based on query duration:
< 10 mins -> agg_counter_1min (High detail)
< 30 mins -> agg_counter_30min (Medium detail)
< 12 hours -> agg_counter_1hour (Balanced)
> 12 hours -> agg_counter_1hour (Aggregated to Daily buckets on-the-fly)
SQL-Side Computation: Heavy logic is pushed to the database.
Downtime: Instead of fetching millions of rows to Python, we use SQL CTEs and COUNT(*) FILTER to calculate uptime/downtime seconds instantly.
Alarm Analysis: We use "Gaps and Islands" logic (using ROW_NUMBER()) inside the database to merge continuous zero-production buckets into downtime events, preventing data explosion in the application layer.
Run the included verification script to see all tools in action:
uv run test_kpi_service.pyIdentifies alarms active during downtime periods to diagnose root causes.
Args:
start_time: ISO 8601 string
end_time: ISO 8601 string
| Name | Required | Description | Default |
|---|---|---|---|
| end_time | Yes | ||
| start_time | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only states the tool identifies alarms during downtime, but does not disclose whether it is read-only, performance implications, authorization needs, or any constraints. The behavioral traits are inadequately covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose and two lines for parameter format. No unnecessary words. The structure is front-loaded with the core purpose followed by parameter specifications.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While an output schema exists (reducing need to describe returns), the description lacks contextual details like prerequisites, data freshness, interpretation guidance, or how this tool relates to alarm monitoring workflows. For a diagnostic tool with zero annotations, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It specifies that start_time and end_time are ISO 8601 strings, which adds format info beyond the schema's 'string' type. However, it does not explain the meaning of the time range (e.g., alignment with downtime periods) or provide examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it identifies alarms active during downtime periods for root cause diagnosis. The verb 'identifies' and resource 'alarms' are specific, and it clearly distinguishes from sibling tools which focus on KPIs (downtime_kpi, productivity_kpi, quality_kpi).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for downtime alarm analysis but provides no explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though siblings are different in nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Computes downtime and availability metrics based on production gaps.
Args:
start_time: ISO 8601 string
end_time: ISO 8601 string
| Name | Required | Description | Default |
|---|---|---|---|
| end_time | Yes | ||
| start_time | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully bears the burden of behavioral transparency. The description only states it computes metrics, with no mention of side effects, permissions, rate limits, or data requirements. This is insufficient for a tool that presumably queries or processes data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short with the main sentence front-loaded. The 'Args:' section adds format info but is somewhat redundant given the schema. Overall, it is concise, though the parameter list could be omitted from the description without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values need not be explained. However, the description lacks details on input assumptions (e.g., need for 'production gaps' data), constraints on the time range, or how it differs from other KPI tools. It is adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists the two parameters and specifies they are ISO 8601 strings, adding format context. However, it does not explain what the parameters represent (e.g., the time range for metrics computation) beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool computes downtime and availability metrics based on production gaps, clearly indicating the verb and resource. However, it does not specify which exact metrics are computed, leaving some ambiguity but still distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like get_downtime_alarms_analysis or get_kpi_summary. No context or exclusions are provided, leaving the agent with no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bundles Productivity, Quality, and Downtime KPIs into a single summary.
Args:
start_time: ISO 8601 string
end_time: ISO 8601 string
| Name | Required | Description | Default |
|---|---|---|---|
| end_time | Yes | ||
| start_time | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states it bundles KPIs, without mentioning auth needs, data scope, performance implications, or any side effects. This is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, with no wasted words. It efficiently conveys the tool's purpose and parameter format. However, it could include more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, no nested objects) and the presence of an output schema, the description covers the basic function. However, it lacks guidance on usage context and does not compensate for missing annotations. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add meaning. It provides format ('ISO 8601 string') which adds value beyond the bare schema, but does not explain the expected time range, relationship between start and end, or constraints. The parameter names are self-explanatory, limiting the need for extensive semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool bundles three specific KPIs (Productivity, Quality, Downtime) into a single summary, using a clear verb+resource structure. It distinguishes itself from sibling tools by consolidating what they do individually.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining a combined KPI view, but lacks explicit guidance on when to use this tool versus the individual KPI siblings. No conditions, prerequisites, or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Computes productivity metrics for a given time range.
Args:
start_time: ISO 8601 string (e.g., '2025-12-01T00:00:00Z')
end_time: ISO 8601 string (e.g., '2025-12-07T23:59:59Z')
| Name | Required | Description | Default |
|---|---|---|---|
| end_time | Yes | ||
| start_time | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations and the description does not disclose any behavioral traits such as read-only, auth needs, or rate limits. The description only states the tool computes metrics, which is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise docstring-style description with parameter list. Could be more front-loaded, but no superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return values are covered. However, the description lacks details on what 'productivity metrics' includes and any limitations on the time range.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 0%, the description provides ISO 8601 format examples for start_time and end_time, adding meaningful guidance beyond the schema's bare 'string' type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it computes productivity metrics for a time range, distinguishing it from sibling tools like get_downtime_kpi or get_quality_kpi.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like get_downtime_kpi, or what constraints apply (e.g., maximum time range).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Computes quality metrics (Yield %, Defect Rate %) for a given time range.
Args:
start_time: ISO 8601 string
end_time: ISO 8601 string
| Name | Required | Description | Default |
|---|---|---|---|
| end_time | Yes | ||
| start_time | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states metrics are 'computed', implying a read-only operation, but does not confirm safety, data freshness, or any constraints like time range limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences for purpose then parameter list. Front-loaded with intent, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple KPI tool. Covers parameters and basic output metrics, but missing details on aggregation level, error handling for invalid ranges, and description of return structure (though output schema exists).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds specific format information for both parameters (ISO 8601 strings), which goes beyond the schema's type-only definition. However, it does not explain acceptable date ranges or timezone handling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool computes quality metrics (Yield %, Defect Rate %) for a given time range. The specific metrics differentiate it from sibling KPI tools (downtime, productivity, summary).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Does not provide any guidance on when to use this tool versus alternatives. No mention of prerequisites, exclusions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct aspect of factory analytics (downtime alarms, downtime KPI, summary KPI, productivity KPI, quality KPI) with no functional overlap. An agent can clearly distinguish based on tool names and descriptions.
All tools follow a consistent `get_<domain>_<detail>` pattern using snake_case, with no deviations. This makes tool discovery and selection predictable.
With 5 tools, the server is well-scoped for factory intelligence. It covers core KPI areas without being overwhelming or too sparse.
The tool set provides essential KPI retrieval and downtime alarm analysis, covering productivity, quality, and downtime. A minor gap is the lack of raw alarm or production data access, but the summary and specific KPI tools cover most agent needs.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Industrial glossary, protocol reference, technical search and OEE calculation. Read-only.
Cross-OEM industrial machine intelligence: identity, normalization, automation, attestation.
Data observability tools for engineering teams: alerts, freshness, schema drift, lineage, quality.
Generate answers & visualizations from your engineering data to track software development health.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lvshrd/Factory-Intelligence-MCP-Server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
