@eloquentjs/mcp

Model Context Protocol server for EloquentJS. Lets AI agents (Claude.ai, Cursor, Windsurf, GitHub Copilot) query your database, introspect your models, run migrations, generate code, and get contextual help — all from inside the AI chat window.

npm install -g @eloquentjs/mcp
# or per-project
npm install --save-dev @eloquentjs/mcp

Powered by @modelcontextprotocol/sdk v1.27.1 — supports MCP protocol 2025-11-25, future transports (HTTP/SSE), and automatic version negotiation.

What This Does

The MCP server exposes 21 tools that AI coding agents can call directly. Instead of reading your code manually or guessing at your schema, the agent can:

• Call list_models → get all models, fields, relations, casts in structured JSON
• Call describe_database_schema → see live columns and indexes from the actual database
• Call query_model → run a safe SELECT query to explore real data
• Call get_help topic="soft-deletes" → get docs and copy-paste examples instantly
• Call nlp_query query="10 most recent active users with their posts" → get the QueryBuilder code
• Call generate_model → scaffold a model + migration + factory with exact field types
• Call run_migrations → apply pending schema changes

Quick Start

Claude Desktop

~/.claude/mcp_config.json:

{
  "mcpServers": {
    "eloquentjs": {
      "command": "npx",
      "args": ["@eloquentjs/mcp", "--cwd", "/absolute/path/to/your/project"]
    }
  }
}

Restart Claude Desktop. EloquentJS tools appear automatically.

Cursor

Settings → MCP Servers → Add:

{
  "name": "eloquentjs",
  "command": "npx @eloquentjs/mcp --cwd ${workspaceFolder}"
}

Windsurf

.windsurf/mcp.json:

{
  "servers": {
    "eloquentjs": {
      "command": "eloquent-mcp",
      "args": ["--cwd", "${workspaceFolder}"]
    }
  }
}

Run manually

# In your project directory
npx @eloquentjs/mcp

# Explicit path
eloquent-mcp --cwd /path/to/project

All 21 Tools

Introspection (5 tools — read-only, no DB required for model tools)

| Tool | Description | |---|---| | list_models | All models: fields with types, relations, casts, scopes, graphql config | | describe_model | Full introspection of one model — every field, relation, scope, hook | | list_migrations | Status of all migrations (ran/pending/batch number/timestamp) | | describe_database_schema | Live table/column/index/FK info from the database | | get_project_structure | Config file, paths, installed packages, model/migration counts |

Code Generation (5 tools)

| Tool | Key params | Description | |---|---|---| | generate_model | name, fields{}, relations[], write? | Generate model (+ optional migration/factory/seeder) | | generate_migration | name, fromModel?, write? | Migration with smart templates (create/add/drop/rename) | | generate_graphql_schema | models[]?, pagination?, write? | Full GraphQL SDL from all models | | generate_typescript_types | models[]?, write? | TypeScript interfaces from all models | | generate_openapi_spec | models[]?, format?, write? | OpenAPI 3.0 spec (JSON or YAML) |

All generation tools return code as a string by default. Pass write: true to save files to disk.

Query & Execution (6 tools)

| Tool | Key params | Description | |---|---|---| | query_model | model, where{}?, orderBy?, limit?, with[]? | Safe SELECT (100 row cap) | | run_raw_query | sql (SELECT/EXPLAIN only), params[]? | Raw SQL — SELECT and EXPLAIN only | | run_migrations | dryRun? | Run pending migrations (or preview with dryRun) | | rollback_migration | step? | Roll back last N batches | | migration_status | — | All migrations with ran/pending/batch info | | run_seeder | seeder? | Execute a seeder class |

Developer Help (5 tools)

| Tool | Key params | Description | |---|---|---| | get_help | topic or search | Docs + quick-start code for any topic | | get_method_signature | method | Exact signature, return type, description | | get_examples | topic | Copy-paste code for common patterns | | nlp_query | query, execute? | Natural language → QueryBuilder chain | | nlp_crud | instruction, execute? | Natural language → CRUD operation code |

get_help topics

model · query-builder · relations · casts · scopes · hooks · events · soft-deletes · validation · migrations · graphql · api · realtime · mcp

get_examples topics

pagination · eager-loading · transactions · soft-deletes · validation · factory

nlp_query examples

"get the 10 most recent active users with their posts"
"count all admin users created this week"
"find posts created today ordered by title"
"get users with their roles oldest first"

nlp_crud examples

"create a User named Alice with email [email protected]"
"update User 42 set is_admin to true"
"delete Post 7"
"find User with id 5"

Example Agent Interactions

"What models do I have?"

Agent calls: list_models
→ Gets: JSON with all model names, tables, fields, relations, casts, scopes
No file reading needed.

"Add an avatar_url field to User"

1. describe_model User → current schema
2. generate_migration add_avatar_url_to_users → migration code
3. run_migrations → apply it
4. generate_typescript_types → update types
All in one conversation.

"Show me the 5 most recent users"

Agent calls: query_model { model: "User", orderBy: "created_at", order: "desc", limit: 5 }
→ Gets: real data from the database

"How do I paginate in EloquentJS?"

Agent calls: get_help { topic: "query-builder" }
→ Gets: full docs with pagination code example

Agent calls: get_examples { topic: "pagination" }
→ Gets: copy-paste pagination code

"Generate a BlogPost model"

Agent calls: generate_model {
  name: "BlogPost",
  fields: { title: "string", body: "text", is_published: "boolean", views: "integer" },
  relations: [{ name: "user", type: "belongsTo", related: "User" }],
  withMigration: true,
  withFactory: true,
  write: true
}
→ Creates: BlogPost.js, 20240321_create_blog_posts_table.js, BlogPostFactory.js

Prompts

Three guided prompts help agents follow best practices:

| Prompt | Description | |---|---| | scaffold_feature | Step-by-step: introspect → generate → migrate → types | | debug_query | Check schema → describe model → fix N+1 and operators | | review_migrations | List pending → flag dangerous changes → production safety check |

In Claude Desktop, these appear in the "Insert prompt" menu.

Resources

Three readable resources agents can reference:

| URI | Description | |---|---| | eloquentjs://schema | Full model schema as JSON | | eloquentjs://models | Model list with file paths | | eloquentjs://config | Current eloquent.config.js |

Agent Files

The agent-files/ directory in the root of this repo contains ready-to-use files for AI tools that don't use MCP:

• CLAUDE.md — drop in project root, Claude reads it automatically
• GEMINI.md — same for Gemini-based tools
• .cursorrules — Cursor rules file
• .windsurfrules — Windsurf rules file
• copilot-instructions.md → copy to .github/copilot-instructions.md
• skills/db-skill.md — deep database patterns
• skills/api-skill.md — REST API patterns
• skills/mcp-skill.md — MCP setup and tool reference

Security

• query_model — only SELECT queries via QueryBuilder; 100 row cap
• run_raw_query — only SELECT, WITH, EXPLAIN; throws immediately on INSERT/UPDATE/DELETE/DROP
• generate_* — returns code strings by default; write: true required to touch the filesystem
• run_migrations / run_seeder — use your eloquent.config.js connection settings
• No credentials are exposed through MCP tools

Programmatic Use

import { createServer, startStdio } from '@eloquentjs/mcp'

// Create server instance with custom config
const server = createServer({
  cwd: process.cwd(),
  config: {
    paths:      { models: 'src/models', migrations: 'src/migrations' },
    connection: { driver: 'pgsql', url: process.env.DATABASE_URL },
  },
})

// Start on stdio (standard MCP transport)
await startStdio({ cwd: process.cwd() })

Protocol

Built on the official @modelcontextprotocol/sdk v1.27.1. Supports MCP protocol version 2025-11-25 over stdio (JSON-RPC 2.0 with Content-Length framing). Server capabilities: tools, resources, prompts.

License

MIT