Skip to main content
Glama
velinussage

mysql-context-mcp

by velinussage

mysql-context-mcp

Light stdio MCP server. A local binlog indexer records ROW-format MySQL changes. Agents pull compact field diffs (from / to) into context. No UI.

License: MIT. Do not commit DSNs. See SECURITY.md.

Modes

Mode

What you get

Deploy cost

binlog (default)

Real before/after from the binary log, served as field diffs

Replica grants + ROW binlog

outbox

Real before/after from table triggers

One extra table + 3 triggers per watched table

watermark

Current rows newer than updated_at (no before-image)

Config only. Not a diff.

recent_changes in binlog mode returns the field diff only. Pass full: true or call get_diff when you need the whole before/after images.

Related MCP server: dynamic-db-mcp-server

MySQL setup (binlog)

[mysqld]
server-id = 1
log_bin = mysql-bin
binlog_format = ROW
binlog_row_image = FULL
binlog_row_metadata = FULL
GRANT REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'agent'@'%';

binlog_row_image=FULL is what makes UPDATE events carry a before image. MINIMAL/NOBLOB will index inserts and deletes, but updates will look like partial rows.

Check the server, then run the MCP:

git clone https://github.com/velinussage/mysql-context-mcp.git
cd mysql-context-mcp
npm install
cp config.example.yaml mysql-context.yaml
export MYSQL_CONTEXT_DSN='mysql://agent@127.0.0.1:3306/app'
export MYSQL_CONTEXT_PASSWORD  # set in the environment, not in this file
npx tsx src/install.ts   # preflight: log_bin / ROW / FULL
npx tsx src/server.ts

The indexer writes a local event log under the process home directory (~/.mysql-context/<database>-binlog/). Override with MYSQL_CONTEXT_INDEX. The MCP process tails the binlog while it is running. You can also run npx tsx src/indexer.ts as a long-lived tailer and keep the MCP read-only against the same index directory.

Tools

Tool

Use

recent_changes

Unacked field diffs, capped JSON. Optional table, full.

get_diff

One change, including before/after images.

ack_changes

Mark seen so they leave the next pull.

There is no execute_sql and no install tool on the MCP server.

Attach to a harness

{
  "mcpServers": {
    "mysql-context": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": ".",
      "env": {
        "MYSQL_CONTEXT_CONFIG": "./mysql-context.yaml",
        "MYSQL_CONTEXT_DSN": "${MYSQL_CONTEXT_DSN}",
        "MYSQL_CONTEXT_PASSWORD": "${MYSQL_CONTEXT_PASSWORD}"
      }
    }
  }
}

Set cwd to the clone. Keep credentials in the process environment.

Claude Agent SDK:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "What changed in MySQL? Use recent_changes and cite the field diffs.",
  options: {
    mcpServers: {
      "mysql-context": {
        command: "npx",
        args: ["tsx", "src/server.ts"],
        env: {
          MYSQL_CONTEXT_CONFIG: "./mysql-context.yaml",
          MYSQL_CONTEXT_DSN: process.env.MYSQL_CONTEXT_DSN!,
          MYSQL_CONTEXT_PASSWORD: process.env.MYSQL_CONTEXT_PASSWORD!,
        },
      },
    },
    allowedTools: [
      "mcp__mysql-context__recent_changes",
      "mcp__mysql-context__get_diff",
      "mcp__mysql-context__ack_changes",
    ],
  },
})) {
  // ...
}

Skill

Copy skill/mysql-context/SKILL.md into the project skills dir so the agent calls recent_changes and treats diff as the change, not the live row.

When this is the wrong tool

Use something else when you need:

Need

Why not this

Use instead

Current table rows (“what is in orders now?”)

This indexes changes, not live state. Watermark mode is a last-resort SELECT and is not a diff.

A read-only SQL MCP, or query MySQL yourself

Arbitrary SQL, writes, or schema changes

There is no execute_sql on purpose.

A separate, tightly scoped SQL tool

A UI, search page, or ops dashboard

This is stdio MCP + a local event log only.

dbtrail or a CDC product with a UI

A warehouse, Kafka stream, or analytics replica

The index is a short, local, single-agent tail. It is not a pipeline.

Debezium, Maxwell, or a managed CDC replica

Forever history of every row, many consumers

The local index caps and drops acked events.

A binlog consumer that writes to durable storage

Statement-based or MIXED binlog, or no replica grants

ROW + FULL row image and REPLICATION SLAVE/CLIENT are required for real before/after.

Outbox mode (triggers) if you can install them; otherwise do not pretend you have diffs

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to interact with a MySQL database using natural language, automating SQL tasks like querying, inserting, updating, and deleting data.
    1
    -
  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to interact with PostgreSQL or MySQL databases using natural language. Supports SQL queries, schema discovery, and pre-built aggregations without writing SQL.
    289 npm
    MIT
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to interact with MySQL databases through structured tools for metadata search, performance analysis, large table insights, lock diagnostics, and slow query analysis.
    9
    -