# CompanyLens MCP Server

[![npm version](https://img.shields.io/npm/v/companylens-mcp.svg)](https://www.npmjs.com/package/companylens-mcp)
[![smithery badge](https://smithery.ai/badge/companylens-mcp)](https://smithery.ai/server/companylens-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

> Corporate intelligence for AI agents. Search companies, get SEC filings, screen sanctions, check government contracts — all via [Model Context Protocol](https://modelcontextprotocol.io/).

CompanyLens MCP gives your AI assistant access to real corporate data from official government sources. No web scraping, no hallucinations — verified data from SEC EDGAR, UK Companies House, OpenSanctions, and USAspending.gov.

---

## Available Tools

| Tool | Description | Data Source |
|------|-------------|-------------|
| `company_search` | Search companies by name or ticker | SEC EDGAR, Companies House |
| `company_profile` | Full corporate profile — financials, filings, officers, registration | SEC EDGAR, Companies House |
| `company_sanctions_check` | Screen against 75+ global sanctions lists | OpenSanctions (OFAC, EU, UN, HMT) |
| `company_contracts` | US government contracts and open opportunities | USAspending.gov, SAM.gov |
| `company_court_cases` | Federal court cases and litigation history | CourtListener / RECAP |

## Quick Start

### Claude Desktop

```bash
claude mcp add companylens -- npx companylens-mcp
```

### Claude Code (CLI)

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "companylens": {
      "command": "npx",
      "args": ["companylens-mcp"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "companylens": {
      "command": "npx",
      "args": ["companylens-mcp"]
    }
  }
}
```

### Windsurf

Add to `~/.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "companylens": {
      "command": "npx",
      "args": ["companylens-mcp"]
    }
  }
}
```

### Smithery

[![Install on Smithery](https://smithery.ai/badge/companylens-mcp)](https://smithery.ai/server/companylens-mcp)

```bash
npx -y @smithery/cli install companylens-mcp --client claude
```

## Usage Examples

Once connected, ask your AI assistant:

**Company Research**
- "Search for Apple Inc and show me their latest SEC filings"
- "Get the full profile for Microsoft — revenue, officers, SIC codes"
- "Look up Rolls Royce in the UK Companies House registry"

**Compliance & Risk**
- "Screen Gazprom against global sanctions lists"
- "Check if this company has any OFAC matches"
- "Run a sanctions check on all companies in my spreadsheet"

**Government Contracts**
- "What government contracts does Boeing have?"
- "Show me the top federal contracts for Lockheed Martin"
- "Are there any open SAM.gov opportunities for this vendor?"

**Legal Research**
- "Find federal court cases involving Tesla"
- "What litigation history does Johnson & Johnson have?"

## How It Works

```
AI Assistant  →  CompanyLens MCP  →  CompanyLens API  →  Government Sources
                  (this server)       (REST backend)      SEC, CH, OFAC, SAM.gov
```

1. Your AI calls `company_search` with a company name
2. CompanyLens searches official registries (SEC EDGAR, Companies House)
3. Returns an `entity_id` — a stable identifier for that company
4. Use the `entity_id` with other tools to get profile, sanctions, contracts, court cases

Every response includes an `agent_hint` — a natural-language suggestion for what the AI should do next.

## Data Sources

| Source | Coverage | Data |
|--------|----------|------|
| [SEC EDGAR](https://www.sec.gov/edgar) | US public companies | 10-K, 10-Q filings, XBRL financials, SIC codes |
| [Companies House](https://www.gov.uk/government/organisations/companies-house) | UK companies | Registration, officers, PSC, filing history |
| [OpenSanctions](https://www.opensanctions.org/) | Global | OFAC SDN, EU Consolidated, UN Security Council, HMT + 75 lists |
| [USAspending.gov](https://www.usaspending.gov/) | US federal | Contract awards, amounts, agencies |
| [SAM.gov](https://sam.gov/) | US federal | Active opportunities, entity registration |
| [CourtListener](https://www.courtlistener.com/) | US federal courts | Dockets, case metadata, RECAP archive |

## Configuration

### Custom API URL

By default, the server connects to `https://companylensapi.vercel.app`. To use your own instance:

```bash
COMPANYLENS_API_URL=https://your-api.example.com npx companylens-mcp
```

Or in your MCP config:

```json
{
  "mcpServers": {
    "companylens": {
      "command": "npx",
      "args": ["companylens-mcp"],
      "env": {
        "COMPANYLENS_API_URL": "https://your-api.example.com"
      }
    }
  }
}
```

## Development

```bash
git clone https://github.com/diplv/companylens-mcp.git
cd companylens-mcp
pnpm install
pnpm dev
```

### Build

```bash
pnpm build
```

### Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## API Reference

### company_search

Search companies by name or stock ticker.

**Parameters:**
- `query` (string, required) — Company name or ticker (e.g., "Apple", "AAPL", "Rolls Royce")
- `jurisdiction` (string, optional) — Filter: `us`, `uk`, or `all` (default: `all`)
- `limit` (number, optional) — Max results 1-50 (default: `10`)

**Returns:** List of companies with `entity_id` for use with other tools.

### company_profile

Full corporate profile with financials and registration data.

**Parameters:**
- `entity_id` (string, required) — CompanyLens entity ID from `company_search`

**Returns:** JSON with name, jurisdiction, status, SIC codes, registered address, XBRL financials (revenue, net income, total assets), recent filings, officers list, and data source attribution.

### company_sanctions_check

Screen against global sanctions lists.

**Parameters:**
- `entity_id` (string, required) — CompanyLens entity ID from `company_search`

**Returns:** Boolean `is_sanctioned` flag, match details with confidence scores, and list names. Includes a disclaimer that this is automated screening, not legal advice.

### company_contracts

US government contract awards and opportunities.

**Parameters:**
- `entity_id` (string, required) — CompanyLens entity ID from `company_search`

**Returns:** Awarded contracts (amount, agency, date) and open SAM.gov opportunities.

### company_court_cases

Federal court litigation history.

**Parameters:**
- `entity_id` (string, required) — CompanyLens entity ID from `company_search`

**Returns:** Court cases with case name, court, docket number, filing date, and status.

## Related

- [CompanyLens API](https://github.com/diplv/companylens-api) — The REST API backend powering this MCP server
- [Model Context Protocol](https://modelcontextprotocol.io/) — The open protocol for AI tool integration
- [Smithery](https://smithery.ai/) — MCP server marketplace

## License

MIT