Laravel Tasks API - MCP Server

A Model Context Protocol (MCP) server that connects to your Laravel Tasks API, allowing AI assistants to interact with your task management system.

Features

• ✅ Health check endpoint
• ✅ List all tasks
• ✅ Get task by ID
• ✅ Create new tasks
• ✅ Update existing tasks
• ✅ Delete tasks

Prerequisites

• Python 3.10 or higher
• Laravel API running at http://localhost:8000
• MCP API key from your Laravel application

Installation

1. Install dependencies:

   pip install -r requirements.txt
   

2. Set up environment variables:

   cp .env.example .env
   

   Then edit .env and add your MCP_API_KEY.

Configuration

The server uses the following environment variables:

• API_BASE_URL: Base URL for your Laravel API (default: http://localhost:8000/api/mcp)
• MCP_API_KEY: Your API key for authentication (required)

Running the Server

For Cursor IDE

Add this to your Cursor settings (.cursor/config.json or Cursor settings):

{
  "mcpServers": {
    "laravel-tasks": {
      "command": "python",
      "args": ["/absolute/path/to/MCP Server/server.py"],
      "env": {
        "MCP_API_KEY": "your-api-key-here",
        "API_BASE_URL": "http://localhost:8000/api/mcp"
      }
    }
  }
}

Testing Locally

You can test the server using the MCP Inspector or by running:

python server.py

Available Tools

The MCP server exposes the following tools:

1. health_check - Check API health status
2. list_tasks - Get all tasks
3. get_task - Get a specific task by ID
4. create_task - Create a new task (requires title, optional description and status)
5. update_task - Update an existing task (requires task_id, optional fields to update)
6. delete_task - Delete a task by ID

API Endpoints

The server connects to these Laravel endpoints:

• GET /api/mcp/health - Health check
• GET /api/mcp/tasks - List tasks
• POST /api/mcp/tasks - Create task
• GET /api/mcp/tasks/{id} - Get task
• PUT/PATCH /api/mcp/tasks/{id} - Update task
• DELETE /api/mcp/tasks/{id} - Delete task

Authentication

All requests include authentication headers:

• X-AI-Agent-Api-Key: <your MCP_API_KEY>
• Authorization: Bearer <your MCP_API_KEY>

Project Structure

MCP Server/
├── server.py          # Main entry point - MCP server initialization
├── config.py          # Configuration management class
├── api_client.py      # Laravel API HTTP client class
├── tools.py           # MCP tool definitions and handlers
├── utils.py           # Utility functions
├── requirements.txt   # Python dependencies
├── .env.example      # Environment variables template
└── README.md         # This file

Architecture

The codebase is organized into modular classes:

• Config (config.py): Manages configuration and environment variables
• LaravelAPIClient (api_client.py): Handles all HTTP requests to Laravel API
• TaskTools (tools.py): Defines MCP tools and handles tool execution
• LaravelTasksMCPServer (server.py): Main server class that ties everything together

Troubleshooting

• Connection errors: Ensure your Laravel API is running at http://localhost:8000
• Authentication errors: Verify your MCP_API_KEY is correct
• Import errors: Make sure all dependencies are installed: pip install -r requirements.txt
• Module import errors: Ensure you're running from the project root directory