Get company financials
get_financialsRetrieve structured financial data for UK companies from Companies House filings, including revenue, profit, assets, and equity metrics for current and prior years.
Instructions
Get structured financial data for a UK company, parsed from its iXBRL accounts filed at Companies House. Returns revenue, cost of sales, gross profit, operating profit, net profit, fixed assets, current assets, total equity, net assets, creditors, and average employees for the current and prior reporting year. Also includes accounts type (full/abbreviated/micro/dormant) and a data_quality block indicating which fields were extracted and which were absent from the filing. Cached for 7 days.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| company_number | Yes | Companies House company number, e.g. '00445790' for Tesco PLC |
Implementation Reference
- src/server.ts:138-145 (handler)The handler function for get_financials tool that executes the tool logic. It accepts company_number parameter, calls the API endpoint /company/{company_number}/financials, and returns the structured financial data or error message.
async ({ company_number }) => { try { const data = await api(`/company/${company_number}/financials`); return text(data); } catch (e) { return err(String(e)); } } - src/server.ts:131-136 (schema)Input schema definition for get_financials tool using Zod validation. Defines company_number parameter as a string matching regex pattern ^[A-Z0-9]{1,8}$ (1-8 alphanumeric characters for Companies House numbers).
inputSchema: { company_number: z .string() .regex(/^[A-Z0-9]{1,8}$/) .describe("Companies House company number, e.g. '00445790' for Tesco PLC"), }, - src/server.ts:119-146 (registration)Complete tool registration for get_financials including title, description, inputSchema, and handler. Registers the tool with the MCP server to make it available for use.
server.registerTool( "get_financials", { title: "Get company financials", description: "Get structured financial data for a UK company, parsed from its iXBRL accounts " + "filed at Companies House. Returns revenue, cost of sales, gross profit, operating " + "profit, net profit, fixed assets, current assets, total equity, net assets, " + "creditors, and average employees for the current and prior reporting year. " + "Also includes accounts type (full/abbreviated/micro/dormant) and a data_quality " + "block indicating which fields were extracted and which were absent from the filing. " + "Cached for 7 days.", inputSchema: { company_number: z .string() .regex(/^[A-Z0-9]{1,8}$/) .describe("Companies House company number, e.g. '00445790' for Tesco PLC"), }, }, async ({ company_number }) => { try { const data = await api(`/company/${company_number}/financials`); return text(data); } catch (e) { return err(String(e)); } } ); - src/server.ts:7-25 (helper)Helper function callApi that handles all API requests to the Registrum API. Validates API key, makes HTTP fetch requests with proper headers, and handles error responses. Used by get_financials handler.
export async function callApi( path: string, apiKey: string, baseUrl: string = API_BASE ): Promise<unknown> { if (!apiKey) { throw new Error( "REGISTRUM_API_KEY is not set. Get a free key at https://registrum.co.uk and set it in your MCP client config." ); } const res = await fetch(`${baseUrl}${path}`, { headers: { "X-API-Key": apiKey }, }); if (!res.ok) { const body = await res.text(); throw new Error(`API error ${res.status}: ${body}`); } return res.json(); } - src/server.ts:27-38 (helper)Helper functions text() and err() for formatting tool responses. text() wraps successful API responses as JSON, err() wraps error messages. Used by get_financials handler to return results.
function text(content: unknown) { return { content: [{ type: "text" as const, text: JSON.stringify(content, null, 2) }], }; } function err(message: string) { return { isError: true as const, content: [{ type: "text" as const, text: message }], }; }