Developers

Murphy's Law Archive offers a free REST API, a TypeScript SDK, a command-line interface, an MCP server for AI agents, and machine-readable feeds. Integrate 2,465 laws into your apps, bots, and workflows with no API key.

MCP Server

The Model Context Protocol (MCP) server lets AI agents and LLM-powered tools access Murphy's Laws directly. Install it with a single command:

npx murphys-laws-mcp

Claude Desktop Configuration

Add this to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "murphys-laws": {
      "command": "npx",
      "args": ["-y", "murphys-laws-mcp"]
    }
  }
}

That's it. No API key, no database, no setup.

Available Tools

  • search_laws: Search laws by keyword with optional category filter
  • get_random_law: Get a random Murphy's Law
  • get_law_of_the_day: Get today's featured law (rotates daily)
  • get_law: Get a specific law by ID
  • list_categories: List all categories with slugs and law counts
  • get_laws_by_category: Browse laws in a specific category
  • submit_law: Submit a new law for review

View on npm | Source on GitHub

CLI

murphys-laws-cli wraps the REST API so you can search, inspect, or submit laws from the terminal. Use it for scripting, shell aliases, or a quick morale boost during deploys.

npx murphys-laws-cli random
npx murphys-laws-cli search "computer" --limit 3
npx murphys-laws-cli today --json

Global flags include --json for machine-readable output, --base-url to target a local or self-hosted server, and --user-agent to override the default.

View on npm | Source on GitHub

TypeScript SDK

murphys-laws-sdk is a small typed client for the REST API. Zero runtime dependencies, uses the platform fetch, and ships ESM types.

import { MurphysLawsClient } from 'murphys-laws-sdk';

const client = new MurphysLawsClient({ userAgent: 'my-app/1.0' });
const law = await client.getRandomLaw();
console.log(law.text);

View on npm | Source on GitHub

REST API

The REST API is free and requires no authentication for read endpoints. JSON endpoints return JSON, while feeds and Open Graph images use their standard media types. All versioned endpoints live under /api/v1/ and are stable.

Base URL: https://murphys-laws.com

Method Selected endpoint Description
GET /api/v1/laws List and search laws. Params: q, category_slug, limit, offset, sort, order
GET /api/v1/laws/:id Get a single law with attributions and category
GET /api/v1/laws/random Get a random published law
GET /api/v1/law-of-day Today's featured law (selected daily by popularity)
GET /api/v1/categories All categories with law counts
GET /api/v1/categories/:id Single category details
POST /api/v1/laws Submit a new law for review

Example

curl -H 'User-Agent: my-app/1.0' "https://murphys-laws.com/api/v1/laws?q=computer&limit=2"

Scripted clients should send a meaningful User-Agent. Generic or blank User-Agents may be rate-limited more aggressively.

View the OpenAPI spec | Full API docs

Feeds

Subscribe to new laws via standard feed formats:

  • RSS 2.0: Recent laws and law of the day
  • Atom 1.0: Recent laws and law of the day

Embed a Law

Show a law on your own site with one iframe. Every law's Share menu has a "Copy embed code" button, or build the snippet yourself:

<iframe src="https://murphys-laws.com/embed/law/1" title="Murphy's Law" width="100%" height="220"
  frameborder="0" loading="lazy"></iframe>

Use https://murphys-laws.com/embed/law-of-day to show today's law, which changes every day. The card links back to the archive and is not indexed by search engines.

oEmbed

Sites that support oEmbed (WordPress, Notion, Slack and others) can unfurl a law URL into the same card. Law pages advertise the endpoint, or call it directly:

GET https://murphys-laws.com/api/v1/oembed?url=https://murphys-laws.com/law/1

The endpoint returns JSON only and accepts maxwidth and maxheight. It answers 400 for a URL that is not a law page, 404 for an unknown law and 501 for format=xml.

Machine-Readable Resources

These files help AI crawlers, search engines, and developer tools understand the site:

Versioning and stability

/api/v1/ is stable. We will not rename or remove existing fields, nor change response semantics in incompatible ways. Breaking changes ship under a new prefix (e.g. /api/v2/), and deprecations are announced via Deprecation and Sunset response headers. Additive changes (new optional fields, new endpoints, new headers) may happen at any time within /api/v1/.

Rate Limits

Reads (GET) are not rate-limited today. Treat the X-RateLimit-* response headers as authoritative rather than hard-coding these numbers.

Writes are rate-limited per IP to prevent abuse:

  • Law submissions: 3 per minute
  • Votes: 30 per minute

Write responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset so clients can back off proactively. When rate limited, the API returns 429 Too Many Requests with a Retry-After header.