mysql-context-mcp

Light stdio MCP server. Agents pull compact MySQL row diffs into context. No UI, no replica, no Kafka.

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

Modes

Mode	What you get	Deploy cost
outbox (default)	Real before/after from table triggers	One extra table + 3 triggers per watched table
watermark	Rows newer than updated_at (no before-image, deletes missed)	Config only

Setup

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://user@127.0.0.1:3306/app'

Put the password in the environment DSN, not in the YAML. Edit tables: to the few tables agents should see.

Install triggers once, from a privileged shell — not from the agent:

npx tsx src/install.ts

After that, run the MCP with a user that can only SELECT watched tables and SELECT/UPDATE the outbox table.

Tools

Tool	Use
recent_changes	Default pull. Unacked diffs, capped, JSON.
get_diff	One change (change_id, or table+pk in watermark mode).
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

Claude Code / Grok / Cursor (project .mcp.json):

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

Set cwd to the clone. Keep MYSQL_CONTEXT_DSN in the process environment, not in a committed file.

Claude Agent SDK:

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

for await (const message of query({
  prompt: "What changed in MySQL since last look? Use recent_changes.",
  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!,
        },
      },
    },
    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 .claude/skills/ or .grok/skills/ so the agent calls recent_changes before reasoning about live rows.

When this is the wrong tool

• You need a full history of every row forever — use a binlog indexer
• You need a live analytics replica — use a CDC replica
• You need the agent to run arbitrary SQL — do not add that here