MCP Laravel API - Kaipa

MCP (Model Context Protocol) service for Laravel API integration with Cursor.

Features

• 🚀 Retrieve all Laravel routes
• 🗂️ List Eloquent models
• ⚙️ Execute Artisan commands
• 📋 Access Laravel configuration
• 🔗 Direct Docker container integration
• 💾 Redis cache management & operations
• 🔄 Full Redis CRUD operations

Setup

1. Install dependencies

npm install

2. Build TypeScript

npm run build

3. Configure Cursor

Add to your Cursor settings (.cursor/rules.mcp.json or settings):

{
  "mcpServers": {
    "laravel-api": {
      "command": "node",
      "args": ["/var/www/ai-tools/mcp-laravel-api-kaitori/dist/server.js"],
      "env": {
        "APP_NAME": "kaipa",
        "DB_HOST": "db",
        "DB_PORT": "3306",
        "APP_PORT": "8181",
        "REDIS_HOST": "redis",
        "REDIS_PORT": "6379"
      }
    }
  }
}

4. Start the service

Development mode:

npm run mcp-dev

Production mode:

npm start

Available Tools

Laravel Tools

get_routes

Get all Laravel API routes with optional filtering.

get_routes({ method: "GET", path: "api" })

artisan_command

Execute any Artisan command in the Laravel container.

artisan_command({ command: "migrate", args: ["--fresh"] })

get_models

List all Eloquent models in the application.

get_config

Access Laravel configuration settings.

Redis Tools

redis_get

Retrieve a value from Redis cache.

redis_get({ key: "user:123" })

redis_set

Store a value in Redis cache with optional TTL.

redis_set({ key: "user:123", value: "John Doe", ttl: 3600 })

redis_delete

Delete one or more keys from Redis.

redis_delete({ key: "user:123" })

redis_keys

Find keys matching a pattern.

redis_keys({ pattern: "cache:*" })

redis_exists

Check if a key exists in Redis.

redis_exists({ key: "user:123" })

redis_flush_db

Clear all data in the current Redis database (use with caution).

redis_flush_db({})

Environment Variables

Required

• APP_NAME - Application name (default: kaipa)
• DB_HOST - Database host (default: db)
• DB_PORT - Database port (default: 3306)
• APP_PORT - Application port (default: 8181)

Optional (Redis)

• REDIS_HOST - Redis server host (default: redis)
• REDIS_PORT - Redis server port (default: 6379)
• REDIS_PASSWORD - Redis authentication password (optional)
• REDIS_DB - Redis database number (default: 0)

Docker Integration

This MCP service communicates with your Laravel API and Redis running in Docker:

• Laravel Container Pattern: {APP_NAME}_{APP_ENV}_php
  • Default: kaipa_local_php
• Redis Container: redis service
  • Default connection: redis:6379

Make sure your Docker containers are running:

docker-compose up -d

Usage in Cursor

Once configured, you can:

1. View API routes: @laravel://routes
2. List models: @laravel://models
3. Run migrations: Execute artisan_command with migrate
4. Access configuration: @laravel://config
5. Manage Redis cache: Use Redis tools for cache operations
6. Monitor cache keys: Use redis_keys with patterns

Example Redis Operations

Cache user data:

redis_set({ key: "user:123:data", value: "{\"id\":123,\"name\":\"John\"}", ttl: 86400 })

Retrieve cached data:

redis_get({ key: "user:123:data" })

Find all session keys:

redis_keys({ pattern: "session:*" })

Clear cache on deploy:

redis_flush_db({})

Troubleshooting

• Docker connection error: Ensure Docker daemon is running and containers are active
• Redis not available: Check if Redis container is running. MCP continues to work without Redis
• Command timeout: Verify Laravel container is responding
• Route list empty: Verify Laravel application is properly initialized

Project Structure

/var/www/ai-tools/mcp-laravel-api-kaitori/
├── src/
│   ├── server.ts              # MCP server with Laravel & Redis
│   ├── services/
│   │   └── redis.service.ts   # Redis client wrapper
│   └── index.ts               # Exports
├── dist/                      # Compiled JavaScript
├── .cursor/
│   └── rules.mcp.json         # Cursor MCP config
├── docs/
│   └── laravel_setup/         # Laravel Docker config
├── package.json               # Dependencies
├── tsconfig.json              # TypeScript config
└── README.md                  # This file

Development

Build changes

npm run build

Test server startup

timeout 3 npm start || echo "Server working"

Install new packages

npm install <package-name>
npm run build

Contributing

When adding new features:

1. Add tool definitions to ListToolsRequestSchema
2. Implement tool logic in CallToolRequestSchema
3. Run npm run build to verify TypeScript
4. Test with npm start