# Unofficial TrustLayer MCP Server
**Unofficial** community Model Context Protocol (MCP) server for the **Public** TrustLayer API - read-only access.
## Overview
This MCP server provides read-only access to the **Public** TrustLayer API data, allowing integration with:
**API Documentation:** This server implements the **Public** TrustLayer Platform API v1.0 and follows the public API documentation available at [https://developers.trustlayer.io/](https://developers.trustlayer.io/).
- Cursor IDE
- n8n workflows
- Claude Desktop
- Other MCP-compatible tools
## Features
- **Read-Only Access**: Only GET operations are supported (no create, update, or delete)
- **Resources**: List all TrustLayer entities (Parties, Documents, Projects, etc.)
- **Tools**: Query specific entities by ID or list with filters
- **JSON Responses**: All data returned as structured JSON
- **HTTP Transport**: Deploy as HTTP server for remote access
- **Token Authentication**: Support for per-request token via Authorization header
## Prerequisites
- Python 3.11+
- TrustLayer API token
## Installation
1. Navigate to the mcp-server directory:
```bash
cd mcp-server
```
2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install dependencies:
```bash
pip install -r requirements.txt
```
4. Create a `.env` file:
```bash
cp env.example .env
```
5. Edit `.env` and configure:
```env
TRUSTLAYER_API_BASE_URL=https://api.trustlayer.io
TRUSTLAYER_API_VERSION=v1
# TRUSTLAYER_API_TOKEN is optional for HTTP mode (token from Authorization header)
# Required only for stdio mode
TRUSTLAYER_API_TOKEN=your_api_token_here
```
**Configuration Options:**
- `TRUSTLAYER_API_BASE_URL` - Base URL for TrustLayer API (default: `https://api.trustlayer.io`)
- `TRUSTLAYER_API_VERSION` - API version (default: `v1`)
- `TRUSTLAYER_API_TOKEN` - API token (required for stdio mode, optional for HTTP mode)
## Usage
### Running the MCP Server
The MCP server can run in two modes:
#### 1. Stdio Mode (for local MCP clients)
The MCP server runs via stdio and is typically started by MCP clients. To test manually:
**Option 1: Using the wrapper script (recommended):**
```bash
# Make sure the script is executable
chmod +x run_server.sh
# Run the server
./run_server.sh
```
**Option 2: Direct Python execution:**
```bash
# Activate virtual environment
source venv/bin/activate # On Windows: venv\Scripts\activate
# Run the server
python -m src.server
```
#### 2. HTTP Mode (for remote access)
To run the MCP server as an HTTP service:
```bash
# Activate virtual environment
source venv/bin/activate # On Windows: venv\Scripts\activate
# Run the HTTP server
python run_http_server.py
```
The server will be available at `http://localhost:8000` with the following endpoints:
- `http://localhost:8000/` - Health check and server info
- `http://localhost:8000/health` - Health check endpoint
- `http://localhost:8000/mcp` - MCP protocol endpoint
**Note:**
- For **HTTP mode**: Token can be provided via `Authorization` header (recommended) or via `TRUSTLAYER_API_TOKEN` env var
- For **stdio mode**: Token must be set in `TRUSTLAYER_API_TOKEN` env var
#### 3. Docker Mode
To run the MCP server using Docker:
```bash
# Create .env file if it doesn't exist
cp env.example .env
# Edit .env and set TRUSTLAYER_API_TOKEN (optional for HTTP mode)
# Build and start the container
docker-compose up -d
# View logs
docker-compose logs -f
# Stop the container
docker-compose down
```
**Rebuilding the Docker image:**
If you've made changes to the code and need to rebuild the image:
```bash
# Stop and remove containers
docker-compose down
# Rebuild without cache (recommended after code changes)
docker-compose build --no-cache
# Start the container
docker-compose up -d
# Or do it all in one command
docker-compose down && docker-compose build --no-cache && docker-compose up -d
```
**Quick rebuild and restart:**
```bash
# Rebuild and restart in one command
docker-compose up -d --build
```
**Checking if the server is running:**
```bash
# Check container status
docker-compose ps
# Check health endpoint
curl http://localhost:8000/health
# View logs
docker-compose logs --tail=50
```
The server will be available at `http://localhost:8000` with the same endpoints as HTTP mode.
### Production Deployment
#### Systemd Service Setup
For production deployment on Linux servers, you can create a systemd service:
1. Create service file:
```bash
sudo nano /etc/systemd/system/trustlayer-mcp.service
```
2. Add the following content:
```ini
[Unit]
Description=TrustLayer MCP Server
After=network.target
[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/mcp-server
Environment="PATH=/path/to/mcp-server/venv/bin"
EnvironmentFile=/path/to/mcp-server/.env
ExecStart=/path/to/mcp-server/venv/bin/python run_http_server.py
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
3. Activate the service:
```bash
# Reload systemd
sudo systemctl daemon-reload
# Enable auto-start
sudo systemctl enable trustlayer-mcp
# Start the service
sudo systemctl start trustlayer-mcp
# Check status
sudo systemctl status trustlayer-mcp
# View logs
sudo journalctl -u trustlayer-mcp -f
```
#### Nginx Reverse Proxy
For production, it's recommended to use Nginx as a reverse proxy:
1. Create Nginx configuration:
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
# For SSE/streaming
proxy_buffering off;
proxy_cache off;
}
}
```
2. Enable SSL with Let's Encrypt:
```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
```
### Integration with Cursor
#### Option 1: Stdio Mode (Local)
Add to your Cursor settings (`.cursor/mcp.json`):
**Option A: Using the wrapper script (recommended):**
```json
{
"mcpServers": {
"trustlayer": {
"command": "/path/to/mcp-server/run_server.sh",
"cwd": "/path/to/mcp-server",
"env": {
"TRUSTLAYER_API_TOKEN": "your_api_token_here",
"TRUSTLAYER_API_BASE_URL": "https://api.trustlayer.io",
"TRUSTLAYER_API_VERSION": "v1"
}
}
}
}
```
**Option B: Direct Python execution:**
```json
{
"mcpServers": {
"trustlayer": {
"command": "/path/to/mcp-server/venv/bin/python3",
"args": ["-m", "src.server"],
"cwd": "/path/to/mcp-server",
"env": {
"PYTHONPATH": "/path/to/mcp-server",
"TRUSTLAYER_API_TOKEN": "your_api_token_here",
"TRUSTLAYER_API_BASE_URL": "https://api.trustlayer.io",
"TRUSTLAYER_API_VERSION": "v1"
}
}
}
}
```
**Example with absolute paths (using wrapper script):**
```json
{
"mcpServers": {
"trustlayer": {
"command": "/path/to/mcp-server/run_server.sh",
"cwd": "/path/to/mcp-server",
"env": {
"TRUSTLAYER_API_TOKEN": "your_api_token_here",
"TRUSTLAYER_API_BASE_URL": "https://api.trustlayer.io",
"TRUSTLAYER_API_VERSION": "v1"
}
}
}
}
```
**Important:**
- When using the wrapper script (`run_server.sh`): Just provide the full path to the script and set `cwd`
- When using direct Python execution: Use the full path to your Python executable in the virtual environment and set `PYTHONPATH`
- Always set `cwd` to the mcp-server directory
#### Option 2: HTTP Mode (Remote)
If you're running the HTTP server separately, connect via HTTP:
**Basic connection (uses token from server config):**
```json
{
"mcpServers": {
"trustlayer": {
"url": "http://localhost:8000/mcp",
"transport": "streamable-http"
}
}
}
```
**With Authorization header (recommended - token per client):**
```json
{
"mcpServers": {
"trustlayer": {
"url": "http://localhost:8000/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer your_api_token_here"
}
}
}
}
```
For remote servers, replace `localhost:8000` with your server's address.
**Note:** When using Authorization header, the token is passed with each request, allowing different clients to use different tokens. This is more secure than storing tokens in server configuration.
### Integration with Claude Desktop
Add to Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
**Stdio Mode:**
```json
{
"mcpServers": {
"trustlayer": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/mcp-server",
"env": {
"TRUSTLAYER_API_TOKEN": "your_token_here",
"TRUSTLAYER_API_BASE_URL": "https://api.trustlayer.io",
"TRUSTLAYER_API_VERSION": "v1"
}
}
}
}
```
**HTTP Mode:**
```json
{
"mcpServers": {
"trustlayer": {
"url": "http://your-server:8000/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer your_api_token_here"
}
}
}
}
```
### Integration with n8n
Use the MCP server as a custom node or via HTTP interface. Start the HTTP server and connect to `http://your-server:8000/mcp`.
**Configuration example:**
```json
{
"url": "http://your-server:8000/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer your_api_token_here"
}
}
```
**Note:** Replace `your-server:8000` with your actual server address and `your_api_token_here` with your TrustLayer API token.
## Available Resources
The MCP server provides resources for:
- `trustlayer://parties/{id}` - Individual parties
- `trustlayer://documents/{id}` - Individual documents
- `trustlayer://projects/{id}` - Individual projects
- `trustlayer://tags/{id}` - Individual tags
- `trustlayer://compliance-profiles/{id}` - Compliance profiles
- `trustlayer://party-types/{id}` - Party types
- `trustlayer://custom-fields/{id}` - Custom fields
- `trustlayer://reports/{id}` - Reports
- `trustlayer://webhooks/{id}` - Webhooks
- `trustlayer://branding/{id}` - Branding configurations
## Available Tools
### Get Operations
- `get_party` - Get a party by ID
- `get_document` - Get a document by ID
- `get_project` - Get a project by ID
- `get_contact` - Get a contact by ID
- `get_party_contacts` - Get all contacts for a party
- `get_party_compliance_profile` - Get compliance profile for a party
- `get_party_compliance_certificate` - Get compliance certificate for a party
- `get_party_document_request` - Get document request for a party
- `get_compliance_profile` - Get a compliance profile by ID
- `get_report` - Get a report by ID
### List Operations
- `list_parties` - List all parties (with optional limit/offset)
- `list_documents` - List all documents (with optional limit/offset)
- `list_projects` - List all projects (with optional limit/offset)
- `list_tags` - List all tags
- `list_compliance_profiles` - List all compliance profiles
- `list_party_types` - List all party types
- `list_custom_fields` - List all custom fields
- `list_reports` - List all reports
- `list_webhooks` - List all webhooks
## Project Structure
```
mcp-server/
├── src/
│ ├── __init__.py
│ ├── server.py # Main MCP server (stdio mode)
│ ├── http_server.py # HTTP MCP server
│ ├── trustlayer_client.py # TrustLayer API client
│ ├── config.py # Configuration
│ ├── resources.py # MCP resources
│ └── tools.py # MCP tools
├── run_server.sh # Stdio server launcher script
├── run_http_server.py # HTTP server launcher
├── test_server.py # Test script to verify server setup
├── test_tools.py # Test script to verify tools registration
├── pyproject.toml
├── requirements.txt
├── Dockerfile # Docker configuration
├── docker-compose.yml # Docker Compose configuration
├── env.example # Environment variables example
└── README.md
```
## Example Usage
### In Cursor/Claude
You can ask questions like:
- "List all parties in TrustLayer"
- "Get details for party ID 12345"
- "Show me all documents for party 12345"
- "What compliance profile does party 12345 have?"
The MCP server will fetch the data from TrustLayer API and return it in a structured format.
## Security
- **Read-Only**: The MCP server only supports GET operations
- **Token Security**: Store API tokens securely in environment variables or use Authorization headers
- **No Data Modification**: No create, update, or delete operations are exposed
- **HTTPS Recommended**: Use HTTPS in production environments
- **Firewall**: Restrict access through firewall to only necessary IPs
## Monitoring
### Health Check
The server provides a health check endpoint:
```bash
curl http://localhost:8000/health
```
Expected response:
```json
{"status": "healthy"}
```
### Logs
**Docker:**
```bash
docker-compose logs -f
```
**Systemd:**
```bash
sudo journalctl -u trustlayer-mcp -f
```
**Local:**
Logs are output to stdout/stderr when running directly.
## Troubleshooting
### Token Issues
Ensure `TRUSTLAYER_API_TOKEN` is set correctly in your environment or `.env` file. For HTTP mode, you can also provide the token via `Authorization` header.
### Connection Issues
- Verify `TRUSTLAYER_API_BASE_URL` is correct
- Check network connectivity
- Review server logs for error messages
- For HTTP mode, ensure the server is running: `curl http://localhost:8000/health`
### Port Already in Use
```bash
# Check what's using port 8000
sudo lsof -i :8000
# Or change the port in run_http_server.py
```
### MCP Client Issues
- Ensure Python is in your PATH
- Verify the MCP server can be started manually
- Check MCP client logs for connection errors
- For stdio mode, verify paths in configuration are correct
### Docker Issues
- Ensure Docker and Docker Compose are installed
- Check container logs: `docker-compose logs`
- Verify `.env` file exists and is properly configured
- Rebuild image if code changes: `docker-compose build --no-cache`
## Development
### Testing
#### Quick Verification Scripts
**Test server setup and imports:**
```bash
python test_server.py
```
This script verifies that:
- Configuration loads correctly
- Server can be imported
- Tools are available
**Test tools registration:**
```bash
python test_tools.py
```
This script verifies that tools are properly registered and can be listed.
#### Test Stdio Server
**Option 1: Using the wrapper script:**
```bash
./run_server.sh
```
**Option 2: Direct Python execution:**
```bash
source venv/bin/activate
python -m src.server
```
#### Test HTTP Server
```bash
# Start the HTTP server
python run_http_server.py
# In another terminal, test the endpoints
curl http://localhost:8000/health
curl http://localhost:8000/
```
### Code Formatting
```bash
black src/
ruff check src/
```
## License
Apache 2.0
