OpenSolar MCP

Give Claude, Cursor, VS Code, and any other MCP client safe, structured access to your OpenSolar organisation.

Unofficial · Self-hosted · Bring your own OpenSolar API token

Quick start · Connect a client · Tools · Configuration · Remote deployment · Security · Troubleshooting

OpenSolar MCP is a Model Context Protocol server for the documented OpenSolar API. It runs on your machine or your infrastructure, uses your own OpenSolar credentials, and gives AI agents a curated set of tools for projects, contacts, systems, files, commercial settings, and Teams sharing.

flowchart LR
    client["MCP client<br/>Claude · Cursor · VS Code · Codex"]
    server["OpenSolar MCP<br/>runs where you run it"]
    api[("OpenSolar API<br/>api.opensolar.com")]
    client -- "stdio or Streamable HTTP" --> server
    server -- "HTTPS with your bearer token" --> api

Highlights

• Curated for agents. A 31-tool default profile covers everyday work. All 75 registered tools are one setting away.

• Semantic operations, not just endpoints. Project and contact search, operational snapshots, stage changes by name, side-by-side system comparison, design summaries, and a read-only share preflight.

• Conservative by design. Searches report whether a match is unique, ambiguous, or incomplete, and agents are told not to guess. Writes are never retried automatically, and read-only mode removes every mutation.

• Faithful to OpenSolar's documentation. Every tool is backed by the official API documentation or by recorded live verification, and writes are exposed only when their request body is established. The evidence for each tool is in the API contract matrix.

• Clean model context. Structured output with published schemas. Credentials, signed URLs, design blobs, and other raw or sensitive fields are removed before they reach the model.

• Current MCP. Built on the official MCP TypeScript SDK v2 for the 2026-07-28 specification, with fallback for clients on earlier protocol versions. Supports stdio and stateless Streamable HTTP, and every tool declares a title, output schema, and behavior annotations.

Related MCP server: AppFolio MCP Server

What you can ask

Quick start

Requirements

• Node.js 24 or newer

• An OpenSolar organisation with API Access enabled

• Your OpenSolar organisation ID and a bearer token

• Raw Data API Access only if you want get_proposal_data or get_project_design

1. See the tools you'll get (no credentials needed):

npx -y @alignco/opensolar-mcp --list-tools

2. Check your configuration and token:

OPENSOLAR_API_TOKEN=your_token OPENSOLAR_ORG_ID=12345 \
  npx -y @alignco/opensolar-mcp --check

--check makes one read of your organisation. Add --no-probe to validate the configuration without contacting OpenSolar.

3. Add it to your MCP client using one of the options below.

Connect your MCP client

Every client needs the same two settings: OPENSOLAR_API_TOKEN and OPENSOLAR_ORG_ID. Replace your_token and 12345 below with your own values.

claude mcp add opensolar \
  -e OPENSOLAR_API_TOKEN=your_token \
  -e OPENSOLAR_ORG_ID=12345 \
  -- npx -y @alignco/opensolar-mcp

Add --scope user to make it available in every project.

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

Restart Claude Desktop after saving.

Use the Add to Cursor button above, or add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

Use the Install in VS Code button above, or add this to .vscode/mcp.json. VS Code prompts for the token and stores it securely:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "opensolar_api_token",
      "description": "OpenSolar API token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "opensolar_org_id",
      "description": "OpenSolar organisation ID"
    }
  ],
  "servers": {
    "opensolar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "${input:opensolar_api_token}",
        "OPENSOLAR_ORG_ID": "${input:opensolar_org_id}"
      }
    }
  }
}

Add this to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

Add this to ~/.codex/config.toml:

[mcp_servers.opensolar]
command = "npx"
args = ["-y", "@alignco/opensolar-mcp"]
env = { OPENSOLAR_API_TOKEN = "your_token", OPENSOLAR_ORG_ID = "12345" }

Add this to ~/.gemini/settings.json:

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

Run npx -y @alignco/opensolar-mcp as a stdio server with OPENSOLAR_API_TOKEN and OPENSOLAR_ORG_ID in its environment. For a client that connects over HTTP, see Remote deployment.

To install the command once instead of through npx:

npm install -g @alignco/opensolar-mcp
opensolar-mcp --version

Tools

Profiles

A profile is a curated operating surface. Toolsets are functional areas you can select directly. Read-only mode and the access-plan filter apply on top of either.

--list-tools always prints the exact surface your settings produce:

npx -y @alignco/opensolar-mcp --list-tools
OPENSOLAR_PROFILE=full npx -y @alignco/opensolar-mcp --list-tools
OPENSOLAR_TOOLSETS=webhooks npx -y @alignco/opensolar-mcp --list-tools

Default agent tools

✏️ marks tools that change OpenSolar data. 🔒 marks tools that need Raw Data API Access.

Set OPENSOLAR_PROFILE=full to expose everything, or name toolsets with OPENSOLAR_TOOLSETS (for example projects,contacts,systems).

Some documented OpenSolar operations are intentionally not exposed because the documentation does not establish their request body — for example creating pricing schemes, payment options, costings, or component activations, and updating workflows or the organisation. The current implementation lists them.

Configuration

OPENSOLAR_TOOLSETS takes precedence over the profile. OPENSOLAR_READ_ONLY and OPENSOLAR_PLAN are applied afterwards. See .env.example for a commented template; the server itself does not load .env files.

Local file uploads

create_private_file uploads a file from the machine running the server, so it is off by default. To enable it, point it at a directory:

export OPENSOLAR_UPLOAD_ROOT=/absolute/path/to/uploads

Relative paths resolve inside that directory. Absolute paths and symlinks are accepted only when their real path stays inside it. The model never sends file bytes.

Downloads through get_private_file and get_system_image are capped at 10 MB. Text content is returned to the model; images and other binary files are returned as MCP image or resource content rather than copied into JSON.

Remote deployment

The server also speaks stateless Streamable HTTP, for clients that connect over the network.

OPENSOLAR_API_TOKEN=your_token OPENSOLAR_ORG_ID=12345 \
  npx -y @alignco/opensolar-mcp --http

On a loopback address, an Authorization: Bearer <token> header takes precedence and the OPENSOLAR_API_TOKEN variable is a local fallback.

Exposing it beyond localhost

Any non-loopback bind requires the OpenSolar bearer token on every MCP request. The OPENSOLAR_API_TOKEN variable is ignored as a fallback, and a malformed Authorization header is rejected.

export OPENSOLAR_ORG_ID=12345
export MCP_HTTP_HOST=0.0.0.0
export MCP_HTTP_ALLOWED_HOSTS=mcp.example.com
npx -y @alignco/opensolar-mcp --http

Connect a client with the token in the request header, for example:

claude mcp add --transport http opensolar https://mcp.example.com/mcp \
  --header "Authorization: Bearer your_token"

Docker

The image runs the HTTP transport as an unprivileged user and includes a health check.

docker pull ghcr.io/align-software-company/opensolar-mcp:latest
docker run --rm \
  -e OPENSOLAR_ORG_ID=12345 \
  -p 127.0.0.1:3000:3000 \
  ghcr.io/align-software-company/opensolar-mcp:latest

To build it from a clone of this repository instead:

docker build -t opensolar-mcp .
docker run --rm \
  -e OPENSOLAR_ORG_ID=12345 \
  -p 127.0.0.1:3000:3000 \
  opensolar-mcp

Inside the container the server binds to 0.0.0.0, so clients must send Authorization: Bearer <token> on every request. The image allows localhost and 127.0.0.1 as Host values; set MCP_HTTP_ALLOWED_HOSTS to your public hostname for anything else.

Security model

• No telemetry. The server sends no analytics or usage data. Its only outbound requests are to the OpenSolar API and to the file and image URLs that OpenSolar returns.

• Your credentials, your process. Tokens stay in your environment or your client's configuration. Nothing is persisted, and this project runs no hosted service.

• Writes are explicit. Mutating tools carry MCP readOnlyHint: false annotations, destructive ones carry destructiveHint: true, and none are retried automatically. OPENSOLAR_READ_ONLY=1 removes them entirely.

• No guessing. A search confirms a target only when it reports resolution: unique, or identifier_match_id for a single exact email or phone match on a complete scan. The server never retries writes and exposes no hidden bulk writes.

• Minimal output. Signed download URLs, integration secrets, webhook secrets, personal identity fields, and raw design data are redacted or omitted.

• Bounded work. Searches, downloads, and Raw Data decompression all have fixed limits. Only ordinary reads retry, and only on HTTP 429, up to three attempts.

• HTTP mode passes your OpenSolar token through. The bearer token a client sends is the OpenSolar token itself, forwarded to OpenSolar. It is not an MCP OAuth token. If several people share one deployment, put an authenticating gateway in front of it.

Please report vulnerabilities privately — see SECURITY.md.

Compatibility

Successful structured tool results also include the same payload serialized as compact JSON text. Clients that do not forward structuredContent can therefore still pass the complete structured result to the model.

Troubleshooting

Logs go to stderr as JSON lines, so stdout stays clean for the MCP protocol.

Development

git clone https://github.com/Align-Software-Company/opensolar-mcp.git
cd opensolar-mcp
corepack enable
pnpm install --frozen-lockfile
pnpm check:all      # repository hygiene, registry metadata, lint, typecheck, offline tests
pnpm build
pnpm test:docker    # build and smoke-test the Docker image

The regular test suite runs offline. Live integration tests read .env.local and run read-only by default; writes need OPENSOLAR_INTEGRATION_WRITES=1 and dedicated fixture records:

pnpm test:integration
OPENSOLAR_INTEGRATION_WRITES=1 pnpm test:integration

Read CONTRIBUTING.md before opening a pull request, especially the rules for OpenSolar API evidence.

Documentation

Contributing

Contributions are welcome. See CONTRIBUTING.md and the Code of Conduct. For security issues, follow SECURITY.md instead of opening an issue.

License

MIT © 2026 Align Software Company.

OpenSolar is a trademark of OpenSolar Pty Ltd. This project is independent and is not endorsed by OpenSolar.