lighthouse-graphql-mcp

cradigan/lighthouse-graphql-mcp

3.1

If you are the rightful owner of lighthouse-graphql-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Lighthouse GraphQL MCP Server is a dynamic server that exposes GraphQL operations from Laravel Lighthouse APIs using the Model Context Protocol (MCP).

Lighthouse GraphQL MCP Server

MCP server that dynamically exposes GraphQL operations from Laravel Lighthouse APIs.

Installation

Dependencies are already installed if you're reading this. If not:

cd ~/.mcp/servers/lighthouse-graphql
npm install

Configuration

  1. Create a .env file from the example:

    cp .env.example .env

  2. Edit .env with your API details:

    GRAPHQL_ENDPOINT=https://your-api.com/graphql
MCP_SCHEMA_ENDPOINT=https://your-api.com/api/mcp/schema
API_TOKEN=your-sanctum-token

Usage with Claude Code

Add to ~/.claude/config.json:

{
  "mcpServers": {
    "lighthouse-graphql": {
      "command": "node",
      "args": ["/Users/chrisradigan/.mcp/servers/lighthouse-graphql/index.js"],
      "env": {
        "GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
        "MCP_SCHEMA_ENDPOINT": "https://your-api.com/api/mcp/schema",
        "API_TOKEN": "your-token"
      }
    }
  }
}

Then restart Claude Code.

Usage with Claude Desktop

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "lighthouse-graphql": {
      "command": "node",
      "args": ["/Users/chrisradigan/.mcp/servers/lighthouse-graphql/index.js"],
      "env": {
        "GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
        "MCP_SCHEMA_ENDPOINT": "https://your-api.com/api/mcp/schema",
        "API_TOKEN": "your-token"
      }
    }
  }
}

Then restart Claude Desktop.

Multiple API Instances

You can configure multiple instances for different projects:

{
  "mcpServers": {
    "ytrack-api": {
      "command": "node",
      "args": ["/Users/chrisradigan/.mcp/servers/lighthouse-graphql/index.js"],
      "env": {
        "GRAPHQL_ENDPOINT": "https://ytrack-api.com/graphql",
        "MCP_SCHEMA_ENDPOINT": "https://ytrack-api.com/api/mcp/schema",
        "API_TOKEN": "token1"
      }
    },
    "another-api": {
      "command": "node",
      "args": ["/Users/chrisradigan/.mcp/servers/lighthouse-graphql/index.js"],
      "env": {
        "GRAPHQL_ENDPOINT": "https://another-api.com/graphql",
        "MCP_SCHEMA_ENDPOINT": "https://another-api.com/api/mcp/schema",
        "API_TOKEN": "token2"
      }
    }
  }
}

How It Works

  1. On startup: Fetches the MCP schema from your API
  2. Builds tools: Creates MCP tools for each GraphQL operation marked with @mcp
  3. Executes operations: When Claude uses a tool, it constructs and executes the corresponding GraphQL query/mutation
  4. Returns results: Formats the response and returns it to Claude

Troubleshooting

Server not starting:

  • Check Node.js version (needs v18+)
  • Verify all dependencies installed: npm install
  • Check .env file exists and is configured

No tools appearing:

  • Verify MCP_SCHEMA_ENDPOINT is accessible
  • Check API_TOKEN is valid
  • Look at Claude Code/Desktop logs for errors

GraphQL errors:

  • Verify GRAPHQL_ENDPOINT is correct
  • Check token has proper permissions
  • Enable DEBUG=true in .env for detailed logs

Testing

You can test the server manually:

node index.js

The server will start and wait for MCP protocol messages on stdin.

Schema Refresh

By default, the schema refreshes every hour. Configure this in .env:

SCHEMA_REFRESH_INTERVAL=3600000  # 1 hour
# or
SCHEMA_REFRESH_INTERVAL=0  # Disable auto-refresh

Development

Watch mode for development:

npm run dev

License

MIT