UK Business Intelligence API & MCP Server

ukbusinessintel.com — Get your free API key

Know everything about any UK business in one API call. Company records, Google reviews, website health, and social profiles — unified into a single JSON response.

Also available as an MCP server for Claude Desktop and Cursor.

Why this over existing Companies House MCP servers?

There are 3 Companies House MCP servers on GitHub — all are thin wrappers around the CH API alone. This is different:

• 4 data sources in one call — Companies House + Google Places + DNS/SSL + social media
• Intelligent matching — automatically links company records to their Google Places listing
• Built-in caching — 7-day cache on company data, 24hr on everything else
• Production-ready — rate limiting, usage tracking, graceful degradation when sources fail

Quick Start

Option 1: MCP Server (for Claude Desktop / Cursor)

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

{
  "mcpServers": {
    "uk-business-intel": {
      "command": "npx",
      "args": ["-y", "uk-business-intelligence-mcp"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-key",
        "COMPANIES_HOUSE_API_KEY": "your-key",
        "GOOGLE_PLACES_API_KEY": "your-key",
        "API_KEY_SALT": "your-random-32-char-string"
      }
    }
  }
}

Then ask Claude: "Look up Greggs in Newcastle" — it returns the full enriched profile.

Option 2: REST API

# 1. Create an API key
curl -X POST https://your-domain.com/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# 2. Enrich a business
curl -X POST https://your-domain.com/api/v1/enrich \
  -H "Content-Type: application/json" \
  -H "x-api-key: ukb_your_key_here" \
  -d '{"business_name": "Greggs", "location": "Newcastle"}'

Data Sources

MCP Server

The MCP server exposes a single tool: enrich_uk_business.

Tool parameters:

How it works: The MCP server calls the enrichment orchestrator directly (no HTTP round-trip). It runs locally on your machine via stdio transport.

Supported clients: Claude Desktop, Cursor, any MCP-compatible client.

API Reference

POST /api/v1/keys

Create an API key. No authentication required. Max 3 active keys per email.

Request:

{
  "email": "developer@example.com",
  "plan": "free"
}

Response (201):

{
  "success": true,
  "data": {
    "api_key": "ukb_a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5",
    "key_prefix": "ukb_a3f8b2c1...",
    "plan": "free",
    "message": "Store this API key securely. It will not be shown again."
  }
}

POST /api/v1/enrich

Enrich a UK business. Requires x-api-key header.

Request:

{
  "business_name": "Greggs",
  "location": "Newcastle",
  "company_number": "00502851",
  "domain": "greggs.co.uk"
}

Only business_name and location are required. company_number and domain are optional — if omitted, they'll be discovered automatically.

Response (200):

{
  "success": true,
  "data": {
    "query": {
      "business_name": "Greggs",
      "location": "Newcastle",
      "company_number": null,
      "domain": null
    },
    "companies_house": {
      "company_number": "00502851",
      "company_name": "GREGGS PLC",
      "company_status": "active",
      "incorporation_date": "1951-09-22",
      "company_type": "plc",
      "sic_codes": ["10710", "47240"],
      "registered_address": {
        "address_line_1": "Greggs House",
        "address_line_2": "Quorum Business Park",
        "locality": "Newcastle Upon Tyne",
        "region": "Tyne and Wear",
        "postal_code": "NE12 8BU",
        "country": "England"
      },
      "directors": [
        {
          "name": "SHERWOOD, Roisin",
          "role": "director",
          "appointed_on": "2019-05-01",
          "resigned_on": null
        }
      ]
    },
    "google_places": {
      "place_id": "ChIJx9k5WQ1yfkgRnx-XPkd9DGw",
      "display_name": "Greggs",
      "formatted_address": "Northumberland St, Newcastle upon Tyne NE1 7DE",
      "rating": 4.1,
      "review_count": 1847,
      "phone": "0191 232 7749",
      "website": "https://www.greggs.co.uk",
      "google_maps_url": "https://maps.google.com/?cid=7771234567890"
    },
    "website": {
      "domain": "greggs.co.uk",
      "is_live": true,
      "http_status": 200,
      "ssl_valid": true,
      "ssl_expiry": "2027-01-15T00:00:00Z"
    },
    "social": {
      "facebook": "https://facebook.com/GreggsFans",
      "instagram": null,
      "linkedin": "https://linkedin.com/company/greggs",
      "twitter": "https://twitter.com/GreggsOfficial"
    },
    "meta": {
      "sources_successful": ["companies_house", "google_places", "dns", "scrape"],
      "sources_failed": [],
      "sources_skipped": [],
      "cached_sources": [],
      "enriched_at": "2026-03-21T14:30:00.000Z",
      "duration_ms": 1247
    }
  }
}

GET /api/v1/usage

Check your current month's usage. Requires x-api-key header.

Response (200):

{
  "success": true,
  "data": {
    "plan": "free",
    "month": "2026-03",
    "lookups_used": 47,
    "lookups_limit": 100,
    "lookups_remaining": 53,
    "overage_count": 0,
    "rate_limit_per_minute": 10
  }
}

DELETE /api/v1/keys

Revoke your API key. Requires x-api-key header (the key being revoked).

GET /api/v1/health

Service health check. No authentication required.

Error Responses

All errors return:

{ "success": false, "error": "Description of the error" }

Pricing

Paid plans allow overage at £0.03 per additional lookup. Free tier hard-stops at 100.

Self-Hosting Setup

Prerequisites

• Node.js 18+
• Supabase project (free tier works)
• Companies House API key (free — register at developer.company-information.service.gov.uk)
• Google Cloud project with Places API (New) enabled

Installation

git clone https://github.com/Fluke-Studio/uk-business-intelligence-mcp.git
cd uk-business-intelligence-mcp
npm install
cp .env.example .env.local
# Fill in your API keys in .env.local

Database Setup

1. Go to your Supabase dashboard > SQL Editor
2. Paste the contents of supabase/migrations/001_initial_schema.sql
3. Click "Run"

This creates all tables, indexes, RPC functions, and cleanup jobs.

Environment Variables

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_ANON_KEY=your-anon-key
COMPANIES_HOUSE_API_KEY=your-ch-api-key
GOOGLE_PLACES_API_KEY=your-google-api-key
API_KEY_SALT=random-32-character-string

Local Development

npm run dev          # Start Next.js dev server (http://localhost:3000)
npm run build        # Production build (Next.js)
npm run build:mcp    # Build MCP server to dist/
npm start            # Production server

Deploy to Vercel

1. Push repo to GitHub
2. Import in Vercel — it auto-detects Next.js
3. Add environment variables in Vercel dashboard (Settings > Environment Variables)
4. Deploy — Vercel handles the rest

Publish MCP Server to npm

# Update package.json with your GitHub username in repository/bugs/homepage URLs
npm run build:mcp    # Builds to dist/
npm publish          # Publishes to npm (prepublishOnly auto-runs build:mcp)

After publishing, anyone can use your MCP server with:

npx uk-business-intelligence-mcp

Architecture

POST /api/v1/enrich
  → Validate body (Zod)
  → Authenticate (x-api-key → SHA-256 hash → DB lookup)
  → Rate limit (fixed-window, DB-backed)
  → Quota check (monthly counter)
  → Enrichment orchestrator
      Round 1 (parallel): Companies House + Google Places
      Round 2 (parallel, if domain found): DNS/SSL Check + Social Scraper
  → Return merged JSON profile

MCP Server (stdio)
  → Receives enrich_uk_business tool call
  → Calls enrichment orchestrator directly (no HTTP)
  → Returns JSON profile to MCP client

• Partial results: If one source fails, the rest still return data
• Smart caching: Supabase-backed with per-source TTLs
• Rate limiting: Atomic Postgres RPC functions (no Redis needed)
• Security: API keys SHA-256 hashed with salt, never stored raw

Tech Stack

• Next.js 14 (App Router, API routes)
• TypeScript (strict mode)
• Supabase (Postgres, auth, caching)
• MCP SDK (Model Context Protocol server)
• Vercel (serverless deployment, London region)
• Zod (request validation)
• Tailwind CSS (landing page)

License

MIT — see LICENSE.