This MCP server manages AI data model projects locally, capturing SQL metadata and semantic context as JSON files. It exposes tools for project setup, schema analysis, and live database interaction via ODBC.
Project Management: Initialize new projects, manage project folders, list available projects, and set the active project. Configure project-level settings (description, SQL dialect, default connection, modeling paradigm, tags).
Context Retrieval: Read the full active project's data model context (connections, tables, columns, keys, relationships) in XML, Markdown, or raw JSON formats.
Connection Management: Create or update ODBC connection descriptors (Trino, SQL Server, Databricks) and list available system DSNs.
Live Schema Interaction: Browse live databases to discover schemas, tables, and columns; refresh column metadata from information_schema while preserving user-defined semantic edits.
Table & Relationship Definition: Update table properties, define primary keys, add foreign key relationships, and specify upstream data lineage.
Semantic Enrichment: Define table grain, document data pitfalls, classify columns (PII/PHI), manage glossary terms, and define measures/KPIs with formulas.
Join Discovery: Scan local .sql files to automatically extract and persist JOIN clauses using sqlglot.
Schema Drift Detection: Diff authored column definitions against the current live database schema to identify discrepancies.
Diagnostics: Tail ODBC query logs for debugging and auditing.
Captures SQL data-model metadata from Databricks via ODBC, exposing table schemas, relationships, and lineage information.
Captures SQL data-model metadata from Trino via ODBC, exposing table schemas, relationships, and lineage information.
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., "@aimm-mcp read the project context"
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.
Local Model Context Protocol server for the AI Model Manager.
Captures SQL data-model metadata as one JSON file per project
(<slug>.aimm.json) and exposes it to Claude Code (or any MCP
client) over stdio.
Fork of the AIMM VS Code extension,
rebuilt in Python with no UI: just tools the agent calls. Both the
VS Code extension and this server read/write the same project-file
format — share a project by committing one .aimm.json to your
repo.
The VS Code extension lives inside an editor. This fork lets you
skip the editor entirely — install once with claude mcp add, and
any Claude session on the machine sees the same models.
Related MCP server: Semantic BI MCP
One line. Claude Code spawns the server via uvx (uv's npx) — no
prior install, no setup.
claude mcp add aimm --scope user -- uvx aimm-mcpFirst connection downloads the package (a few seconds). Subsequent connections are cache-served.
For testing from a local checkout before PyPI, see
LOCAL_INSTALL.md.
Two concepts: machine-local sidecars (always at ~/Documents/AIMM/)
and project files (anywhere you point them, default the same folder).
~/Documents/AIMM/ machine-local, never moves
├── state.json which folder + which active project
├── discovered_joins.json scan output (not project state)
└── diagnostics.log ODBC query append-log
<projects_folder>/ defaults to ~/Documents/AIMM/
├── customer_warehouse.aimm.json one project
├── reporting_model.aimm.json another project
└── …A team checks <projects_folder> into a git repo. The agent runs
aimm_set_projects_folder to point at the local clone, then
aimm_list_projects + aimm_set_active_project to pick one. The
"active project" pointer survives across Claude Code sessions.
No derived snapshots on disk. Renderings (XML / markdown / raw JSON)
happen in-memory when aimm_read_project_context is called.
Three engines via ODBC: trino, sql_server, databricks.
Connection descriptors carry a DSN name (system DSN registered at
the OS level) plus the catalog / database qualifier.
The agent must select an active project before any project-touching tool runs — these tools handle that bootstrap.
aimm_set_projects_folder — point the server at a folder of
.aimm.json files (defaults to ~/Documents/AIMM/). Use to
switch to a team repo of shared projects. Clears the active
pointer.
aimm_list_projects — enumerate .aimm.json files in the
current folder with their internal project name + updated_at.
aimm_set_active_project — pick one as active. Subsequent
tool calls read and write that file.
aimm_show_active_project — report the current pointer state
(folder + active file + on-disk status).
aimm_init_project — create a new <slug>.aimm.json (slug
derived from name) in the current folder, set it as active.
aimm_read_project_context — return the entire active
project. Formats: xml (default), markdown, json (raw bytes
of the active file).
aimm_upsert_connection — create / update a connection
descriptor. Validates Trino catalog requirement.
aimm_list_system_dsns — pyodbc.dataSources() wrapper for
discovery before upsert.
aimm_browse_connection — drill into schemas / tables /
columns on a live connection. Optional case-insensitive search
filter.
aimm_refresh_columns — re-fetch column shapes from
information_schema and merge back into the active project
(preserves user-edited PK / FK / description flags).
aimm_update_table — patch any non-identity field on a
tracked table. Creates on first patch.
aimm_set_primary_key — atomically set primary_keys + flip
is_primary_key on matching columns.
aimm_add_relationship — append an FK edge (idempotent on
duplicates, composite keys supported).
aimm_add_upstream — append a lineage edge.
The structural fields above tell the agent what's there. These
tell it what those things mean — captured once, surfaced on
every subsequent aimm_read_project_context call.
aimm_set_table_grain — one-line "what is a row?" per table.
aimm_add_pitfall — append-with-dedupe to a table's "don't do
this" list.
aimm_set_column_classification — flag a column as
pii / phi / restricted / internal / public.
aimm_add_glossary_term — upsert a domain-vocabulary entry.
aimm_add_measure — upsert a KPI / metric with definition +
formula.
aimm_update_project_config — patch the project header
(description, conventions, dialect, default_connection,
modeling_paradigm, tags).
aimm_scan_folder_for_joins — walk a local folder of .sql
files, extract JOIN clauses via sqlglot (multi-dialect fallback:
tsql → spark → none), persist canonical edges to
~/Documents/AIMM/discovered_joins.json. Works without an active
project.
aimm_show_diagnostics_log — tail of diagnostics.log where
every ODBC query is recorded.
aimm_get_pending_changes — per-tracked-table diff between
authored columns and the live information_schema shape.
Every warehouse this targets exposes an ODBC driver. We never run
user SQL — only information_schema reads for column / table /
schema metadata. Drivers stay read-only at the credential level.
uv sync --dev
uv run python -m aimm_mcp # starts the MCP stdio server
uv run pytest -q # testsMIT.
Bootstrap the AIMM data model at ~/Documents/AIMM/. Creates the folder skeleton (aimm.json + tables/ + connections/ + diagnostics.log) if it doesn't exist. Idempotent — safe to call when already initialised. Required argument: name, a human-readable label for the project that shows up in every context dump. Optional: description, free-text context the agent reads on every call.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Project name (max 120 chars). Required. | |
| description | No | Free-text project context. Max 20,000 chars. Defaults to '' when omitted. Use this to capture the business domain the model covers — agents read it on every call. | |
| dialect | No | Default SQL dialect for the project ('tsql', 'trino', 'spark'). Falls back to 'tsql' when omitted. Engines on individual connections override this for their own queries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses idempotency, folder creation, and parameter roles. It does not mention permissions or side effects, but for a bootstrap tool the information is sufficient.
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?
Two sentences front-load the core purpose and idempotency. Every sentence adds value with no redundancy. Extremely efficient.
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 (3 params, no output schema, single sibling), the description covers essential aspects: purpose, location, idempotency, and parameter explanations. Minor omission of return value but not critical for a bootstrap function.
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 100%, so baseline is 3. The description adds value by explaining the purpose of `name` (human-readable label for context dumps) and `description` (free-text read on every call), and notes dialect default. This enriches understanding beyond the schema.
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's action ('Bootstrap the AIMM data model'), the target location, and the folder skeleton created. It distinguishes itself from the sibling `aimm_read_project_context` by being an initialization tool versus a read tool.
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 explicitly states idempotency ('safe to call when already initialised'), which guides usage. However, it does not provide explicit when-not-to-use scenarios or mention alternatives beyond the implicit contrast with the sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return everything the project records: project header, every connection, every tracked table with its columns / primary keys / FK relationships / upstream lineage, plus the project-tracked joins list. Always call this once at the start of a session before answering data-model questions; the cost is bounded and the payload is the canonical context for every other tool you'll use. Defaults to XML for cross-referential reasoning; pass format: 'markdown' for a leaner prose digest.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format. Defaults to xml. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses return scope, cost bound, default format, and rationale. It lacks explicit statement about safety (e.g., no side effects), but the content implies read-only behavior.
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 concise, with every sentence contributing significant information. It front-loads the main purpose, followed by usage guidance and format explanation, with no redundant 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?
Given the tool's complexity (returns many project details) and lack of output schema, the description covers what is returned, when to use it, and format options. It lacks details on error handling or size limits, but the bounded cost mention mitigates some concerns.
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 100% with one enum parameter. The description adds value by explaining why XML is default ('cross-referential reasoning') and what markdown offers ('leaner prose digest'), going beyond the schema's basic description.
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 'Return everything the project records' and lists all components (header, connections, tables, joins), making the purpose unambiguous. It distinguishes from sibling tool 'aimm_init_project' by focusing on context retrieval.
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 gives a clear directive: 'Always call this once at the start of a session before answering data-model questions', which tells the agent exactly when to use it. It also contrasts with other tools by stating this is the 'canonical context'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a completely distinct purpose: one initializes the project, the other reads its context. There is no overlap or ambiguity.
Both tools follow a consistent 'aimm_verb_noun' pattern (init_project, read_project_context), making naming predictable and clear.
With only 2 tools, the server feels undersized for managing a data model. A more complete set (e.g., adding tables, connections) would be expected.
The server provides initialization and read capabilities only, lacking essential mutation tools like adding tables or connections, making it incomplete for full project management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
A Model Context Protocol server for Wix AI tools
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/DylanCodyBrown/aimm-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
