Creditsafe MCP Server

A Model Context Protocol (MCP) server that provides access to the Creditsafe Credit and Risk API. This server enables AI assistants and other MCP clients to search for companies and directors, retrieve detailed credit reports, and access business intelligence data.

Features

• 🔍 Company Search - Search for companies by name, registration number, address, or other criteria
• 📊 Company Reports - Retrieve detailed credit reports including financial data, credit scores, and directors
• 👤 Director Search - Search for directors and people by name, date of birth, or director number
• 📋 Director Reports - Get detailed reports on individuals including directorships and addresses
• 🌍 Country Access - List available countries for company and director reports
• 🔐 Secure Authentication - Token caching with automatic refresh
• 📄 Flexible Responses - Choose between raw API responses or simplified data formats
• 📑 Smart Pagination - Fetch single pages or automatically retrieve all results

Installation

With npx (no global install)

Runs the published package from the npm registry (downloads on first use):

npx -y @thedistance/creditsafe-mcp-server

Global install

npm install -g @thedistance/creditsafe-mcp-server

From source

git clone <repository-url>
cd creditsafe-mcp-server
npm install
npm run build

Publishing to npm

From the repository root (after npm login to an account that can publish the @thedistance scope):

npm run publish:mcp

Or from creditsafe-mcp-server:

npm publish

Inspect the tarball first with npm run pack:mcp (root) or npm pack (inside creditsafe-mcp-server).

Configuration

Create a .env file in your project directory or set environment variables:

CREDITSAFE_USERNAME=your_username
CREDITSAFE_PASSWORD=your_password
CREDITSAFE_ENVIRONMENT=production  # or "sandbox"

Environment Variables

| Variable | Required | Description | Values | |----------|----------|-------------|---------| | CREDITSAFE_USERNAME | Yes | Your Creditsafe API username | string | | CREDITSAFE_PASSWORD | Yes | Your Creditsafe API password | string | | CREDITSAFE_ENVIRONMENT | No | API environment to use | production (default) or sandbox |

Usage

Claude Desktop Configuration

Add the server to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "creditsafe": {
      "command": "creditsafe-mcp-server",
      "env": {
        "CREDITSAFE_USERNAME": "your_username",
        "CREDITSAFE_PASSWORD": "your_password",
        "CREDITSAFE_ENVIRONMENT": "production"
      }
    }
  }
}

If using npx (package name must match what you publish; default bin is creditsafe-mcp-server):

{
  "mcpServers": {
    "creditsafe": {
      "command": "npx",
      "args": ["-y", "@thedistance/creditsafe-mcp-server"],
      "env": {
        "CREDITSAFE_USERNAME": "your_username",
        "CREDITSAFE_PASSWORD": "your_password",
        "CREDITSAFE_ENVIRONMENT": "production"
      }
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "creditsafe": {
      "command": "node",
      "args": ["/path/to/creditsafe-mcp-server/build/index.js"],
      "env": {
        "CREDITSAFE_USERNAME": "your_username",
        "CREDITSAFE_PASSWORD": "your_password",
        "CREDITSAFE_ENVIRONMENT": "production"
      }
    }
  }
}

Testing with MCP Inspector

npm run inspector

This will open the MCP Inspector UI where you can test the server's tools interactively.

Available Tools

1. search_companies

Search for companies by various criteria.

Parameters:

• countries (required): Comma-separated country codes (e.g., "GB,US")
• name: Company name to search for
• address: Company address
• city: Company city
• postcode: Company postcode/zip code
• regNo: Company registration number
• vatNo: VAT number
• safeNo: Creditsafe company number
• exactMatch: Whether to match company name exactly (boolean)
• page: Page number for pagination (default: 1)
• pageSize: Results per page (default: 10, max: 100)
• returnAll: Fetch all pages automatically (boolean)
• responseFormat: "raw" or "simplified" (default: "raw")

Example:

{
  "countries": "GB",
  "name": "Acme Corporation",
  "city": "London",
  "pageSize": 20
}

2. get_company_report

Retrieve a detailed credit report for a specific company.

Parameters:

• connectId (required): Creditsafe Connect ID from search results
• language: Language code for the report (e.g., "en")
• template: Report template to use
• includeIndicators: Include financial indicators (boolean)
• customData: Custom data to include
• responseFormat: "raw" or "simplified" (default: "raw")

Example:

{
  "connectId": "GB003/0/07989440",
  "language": "en"
}

3. search_directors

Search for directors/people by various criteria.

Parameters:

• countries (required): Comma-separated country codes (e.g., "GB,US")
• firstName: Director first name
• lastName: Director last name
• dateOfBirth: Date of birth (format: YYYY-MM-DD or YYYY-MM)
• localDirectorNumber: Local director identifier (e.g., PNR in GB)
• peopleId: Person/Director identifier
• page: Page number for pagination (default: 1)
• pageSize: Results per page (default: 10, max: 100)
• returnAll: Fetch all pages automatically (boolean)
• responseFormat: "raw" or "simplified" (default: "raw")

Example:

{
  "countries": "GB",
  "firstName": "John",
  "lastName": "Smith",
  "pageSize": 20
}

4. get_director_report

Get a detailed report for a specific director/person.

Parameters:

• peopleId (required): Creditsafe People ID from search results
• responseFormat: "raw" or "simplified" (default: "raw")

Example:

{
  "peopleId": "GB/001/123456789"
}

5. get_available_countries

List countries available for company and/or director reports.

Parameters:

• reportType: Filter by type - "company", "director", or "all" (default: "all")

Example:

{
  "reportType": "company"
}

Response Formats

Raw Format (Default)

Returns the complete API response as-is from Creditsafe. Provides maximum detail but may be complex.

Simplified Format

Returns a cleaned, easy-to-consume version of the data:

Company Search (simplified):

{
  "total": 150,
  "count": 10,
  "companies": [
    {
      "id": "GB003/0/07989440",
      "name": "ACME CORPORATION LTD",
      "country": "GB",
      "registrationNumber": "07989440",
      "creditsafeNumber": "GB003/0/07989440",
      "address": "123 High Street, London, SW1A 1AA",
      "status": "Active",
      "type": "Ltd"
    }
  ]
}

Director Search (simplified):

{
  "total": 50,
  "count": 10,
  "people": [
    {
      "id": "GB/001/123456789",
      "name": "John Smith",
      "firstName": "John",
      "lastName": "Smith",
      "dateOfBirth": "1970-05-15",
      "country": "GB",
      "address": "123 High Street, London, SW1A 1AA",
      "directorships": 5
    }
  ]
}

Pagination Strategies

Single Page (Default)

Use page and pageSize parameters to fetch specific pages:

{
  "countries": "GB",
  "name": "Acme",
  "page": 1,
  "pageSize": 50
}

Auto-Pagination

Set returnAll: true to automatically fetch all results:

{
  "countries": "GB",
  "name": "Acme",
  "returnAll": true
}

Note: Auto-pagination may take time for large result sets.

Architecture

Components

• AuthManager - Handles authentication with token caching and auto-refresh
• CreditsafeClient - HTTP client wrapper with automatic retry on token expiration
• Tools - Individual tool implementations for each operation
• Type Definitions - Full TypeScript types for all API interactions

Authentication Flow

1. First request triggers authentication
2. Bearer token is cached with 55-minute lifetime
3. Token is automatically refreshed when expired
4. 401 responses trigger immediate re-authentication

Error Handling

• Network errors are caught and returned with context
• API errors include Creditsafe error messages and correlation IDs
• Validation errors from Zod schemas provide clear parameter feedback

Development

Build

npm run build

Watch Mode

npm run watch

Project Structure

creditsafe-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── auth.ts               # Authentication manager
│   ├── client.ts             # HTTP client wrapper
│   ├── tools/
│   │   ├── company.ts        # Company tools
│   │   ├── director.ts       # Director tools
│   │   └── access.ts         # Access tools
│   └── types/
│       ├── api.ts            # API types
│       └── config.ts         # Configuration types
├── build/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

API Documentation

For complete Creditsafe API documentation, visit:

• Creditsafe Connect API Documentation

Troubleshooting

Authentication Errors

• Verify CREDITSAFE_USERNAME and CREDITSAFE_PASSWORD are correct
• Check that you're using the correct CREDITSAFE_ENVIRONMENT (production vs sandbox)
• Ensure your Creditsafe account has API access enabled

Empty Results

• Use get_available_countries to verify which countries are available for your account
• Check that country codes are in ISO2 format (e.g., "GB", "US", "DE")
• Try broader search criteria

Rate Limiting

The server includes automatic retry logic, but if you encounter rate limits:

• Reduce pagination size (pageSize)
• Add delays between requests
• Use returnAll sparingly for large datasets

License

MIT

Support

For issues and questions:

• GitHub Issues: [Repository issues page]
• Creditsafe API Support: Contact your Creditsafe account manager

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

Changelog

1.0.0 (2024)

• Initial release
• Company search and reports
• Director search and reports
• Country access listing
• Token caching with auto-refresh
• Flexible response formats
• Smart pagination