Companies Graph MCP Server

An MCP (Model Context Protocol) server that builds and visualizes company relationship networks using the Companies House API. This server creates interactive graph databases showing relationships between companies, officers, and persons with significant control (PSCs).

🎯 Status: Production Ready ✅

Latest Version: v1.0.5 - All known issues resolved!

• ✅ Claude Desktop Integration: Seamless MCP connection with clean JSON communication
• ✅ Web Visualization: Interactive browser interface with automatic port detection
• ✅ Zero Configuration: Works out-of-the-box with simple NPX command
• ✅ Complete Network Analysis: Successfully maps company relationships, officers, and PSCs

Features

• 🔍 Company Search: Search for UK companies by name or registration number
• 📊 Network Building: Automatically build relationship graphs showing company connections
• 🌐 Interactive Visualization: Web-based graph visualization with real-time updates
• 🔒 Security First: Built with enterprise-grade security practices
• 📁 Multiple Export Formats: Export data as JSON, CSV, or GraphML
• ⚡ Zero-Friction Deployment: Run instantly with NPX, no installation required

Quick Start

# Set your Companies House API key
export COMPANIES_HOUSE_API_KEY=xxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxx

# Run the server
npx @superadnim/companies-graph-mcp-server

Installation

Option 1: NPX (Recommended)

No installation required! Simply run:

npx @superadnim/companies-graph-mcp-server

Option 2: Global Installation

npm install -g @superadnim/companies-graph-mcp-server
companies-graph-mcp

Option 3: Local Development

git clone https://github.com/CG-Labs/Companies-House-Graph-MCP.git
cd Companies-House-Graph-MCP
npm install
npm run build
npm start

Configuration

Environment Variables

Create a .env file (see .env.example):

# Required
COMPANIES_HOUSE_API_KEY=your-api-key-here

# Optional - Server Configuration
PORT=3000
WEB_UI_PORT=8080

# Optional - Neo4j Database (only needed for persistent storage)
# Most users should omit these - the server works great without Neo4j!
# NEO4J_URI=bolt://localhost:7687
# NEO4J_USER=neo4j
# NEO4J_PASSWORD=password

# Optional - Security Configuration
RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
RATE_LIMIT_MAX_REQUESTS=100

# Optional - Logging
LOG_LEVEL=info

Claude Desktop Configuration

Add to your Claude Desktop config file:

{
  "mcpServers": {
    "companies-graph": {
      "command": "npx",
      "args": ["@superadnim/companies-graph-mcp-server"],
      "env": {
        "COMPANIES_HOUSE_API_KEY": "xxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxx"
      }
    }
  }
}

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code Configuration

# Add the MCP server
claude-code config add-mcp-server companies-graph npx @superadnim/companies-graph-mcp-server

# Set the API key
export COMPANIES_HOUSE_API_KEY=your-api-key-here

Augment.io Configuration

1. Open Augment.io settings
2. Navigate to MCP Servers
3. Add new server with command: npx @superadnim/companies-graph-mcp-server
4. Configure environment variable:
   • Name: COMPANIES_HOUSE_API_KEY
   • Value: xxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxx

Available Tools

1. search_company

Search for companies by name or registration number.

Parameters:

• query (required): Company name or registration number
• limit (optional): Maximum results (default: 10)

Example:

Search for: "OpenAI"

2. get_company_details

Get detailed information about a specific company.

Parameters:

• companyNumber (required): The company registration number

Example:

Get details for company: "13448826"

3. build_company_network

Build a network graph of company relationships including officers, PSCs, and related companies.

Parameters:

• companyNumber (required): Starting company number
• depth (optional): Relationship depth (default: 2)
• includeInactive (optional): Include dissolved companies (default: false)

Example:

Build network for company "13448826" with depth 2

4. visualize_graph

Open web browser to visualize the company network graph.

Parameters:

• companyNumber (optional): Company to center on
• layout (optional): Graph layout - "force", "hierarchical", or "circular" (default: "force")

Example:

Visualize the graph with force layout

5. export_graph_data

Export the graph data in various formats.

Parameters:

• format (required): Export format - "json", "csv", or "graphml"

Example:

Export graph as JSON

Resources

The server provides access to:

graph://current

The currently loaded company network graph data.

graph://statistics

Statistics about the current graph including node counts, edge counts, and central nodes.

Database Storage Modes

The server supports two storage modes:

🧠 In-Memory Mode (Default)

• Zero setup required - works immediately after installation
• Data stored in JavaScript Maps for ultra-fast access
• Perfect for exploration, testing, and most production use cases
• Temporary storage (data cleared on server restart)
• Recommended for most users

🗃️ Neo4j Mode (Optional)

• Requires a running Neo4j database instance
• Persistent storage across server restarts
• Advanced graph algorithms and Cypher queries
• Better for enterprise deployments with massive datasets
• Only needed for specialized use cases

The server automatically uses in-memory mode unless Neo4j credentials are provided.

Security Features

Authentication & Authorization

• Secure API key management through environment variables
• Support for Azure AD integration (when deployed to Azure)
• OAuth 2.1 framework compliance

Rate Limiting

• Configurable request limits per time window
• Prevents API abuse and ensures fair usage
• Default: 100 requests per 15 minutes

Data Protection

• All API communications over HTTPS
• Input validation and sanitization
• Secure credential storage
• No hardcoded secrets

Content Security

• Helmet.js for secure HTTP headers
• CORS protection
• XSS prevention
• CSP (Content Security Policy) enforcement

Web UI Features

The interactive visualization includes:

• Real-time Updates: WebSocket connection for live graph updates
• Interactive Navigation: Pan, zoom, and click nodes for details
• Search Functionality: Find specific companies or people
• Multiple Layouts: Force-directed, hierarchical, or circular layouts
• Node Information: Click any node to see detailed information
• Export Options: Download graph data in multiple formats

Graph Legend

• 🟢 Green: Companies
• 🔵 Blue: Persons
• 🟠 Orange: Officers
• 🟣 Purple: Persons with Significant Control (PSCs)

Development

Prerequisites

• Node.js 18.0.0 or higher
• TypeScript 5.0 or higher
• Companies House API key

Setup

# Clone the repository
git clone https://github.com/CG-Labs/Companies-House-Graph-MCP.git
cd Companies-House-Graph-MCP

# Install dependencies
npm install

# Run in development mode
npm run dev

Testing

# Run tests
npm test

# Run linting
npm run lint

# Format code
npm run format

Building

# Build for production
npm run build

# Build and run
npm run build && npm start

Deployment

Azure Deployment

For enterprise deployment with Azure AD integration:

1. Create an Azure App Service
2. Configure environment variables
3. Enable Azure AD authentication
4. Deploy using GitHub Actions or Azure DevOps

Docker Deployment

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000 8080
CMD ["npm", "start"]

Troubleshooting

Common Issues

API Key Issues

• Ensure your Companies House API key is valid
• Check that the environment variable is set correctly
• Verify the key has not expired

Connection Issues

• Check firewall settings for ports 3000 and 8080
• Ensure WebSocket connections are allowed
• Verify Companies House API is accessible

Graph Not Loading

• Check browser console for errors
• Ensure data has been fetched using build_company_network
• Verify WebSocket connection is established

Debug Mode

Enable debug logging:

export LOG_LEVEL=debug

API Rate Limits

Companies House API has the following limits:

• 600 requests per 5 minutes
• Some endpoints have additional restrictions

This server implements intelligent rate limiting to stay within these bounds.

Troubleshooting

Common Issues ✅ RESOLVED

Issue: "Unexpected token" or JSON parsing errors in Claude Desktop

Status: ✅ FIXED in v1.0.4
Cause: Colored log output corrupting JSON communication
Solution: Automatic environment detection disables colors in MCP mode

Issue: Web visualization shows "No data loaded"

Status: ✅ FIXED in v1.0.5
Cause: Port conflicts preventing web server startup
Solution: Automatic port detection with fallback (8080 → 8081 → 8082...)

Current Troubleshooting Steps

1. Update to latest version:

   npx @superadnim/companies-graph-mcp-server@latest

2. Verify API key:

   curl -H "Authorization: YOUR_API_KEY" https://api.company-information.service.gov.uk/

3. Check logs:

   • Claude Desktop: ~/Library/Logs/Claude/mcp-server-companies-graph.log
   • Enable debug: Set LOG_LEVEL=debug in environment

4. Test installation:

   # Run the test script included in the package
   npx @superadnim/companies-graph-mcp-server --test

Getting Help

If you encounter issues:

1. Check the TROUBLESHOOTING_NPX.md guide
2. Review recent GitHub Issues
3. Create a new issue with:
   • Node.js version (node --version)
   • NPM version (npm --version)
   • Operating system
   • Error logs

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Documentation: Full Documentation
• Companies House API: developer.company-information.service.gov.uk

Roadmap

✅ Completed (v1.0.5)

• [x] Interactive web visualization
• [x] Real-time WebSocket updates
• [x] Multiple export formats (JSON, CSV, GraphML)
• [x] Automatic port detection
• [x] Clean MCP protocol integration
• [x] Comprehensive error handling

🚀 Upcoming Features

• [ ] Neo4j database persistence
• [ ] Advanced graph algorithms (PageRank, community detection)
• [ ] Bulk company import via CSV/Excel
• [ ] Historical data tracking and timeline view
• [ ] International company support (EU, US)
• [ ] Advanced filtering options (date ranges, company types)
• [ ] GraphQL API endpoint
• [ ] Export to popular analysis tools (Gephi, Cytoscape)

Acknowledgments

Built with:

• Model Context Protocol SDK
• Companies House API
• Vis.js Network
• Express
• TypeScript