OpenSolar MCP

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

[!IMPORTANT]

This project is not affiliated with, endorsed by, or maintained by OpenSolar Pty Ltd. It calls only the public, documented OpenSolar API and does not operate a shared or hosted OpenSolar service.

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.

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

[!TIP]

Standard OpenSolar user tokens expire after seven days. For a long-running setup, create a dedicated OpenSolar user for API work and make it a machine user, whose token does not expire. This server never changes that setting for you.

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 Code

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.

Claude Desktop

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.

Cursor

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" } } } }

VS Code

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}" } } } }

Windsurf

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" } } } }

OpenAI Codex

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" }

Gemini CLI

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" } } } }

Any other MCP client

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

[!TIP]

Start with OPENSOLAR_READ_ONLY=1 in the env block while you get comfortable. It removes every tool that can change OpenSolar data.

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.

| Files & documents | list_private_files · get_private_file · create_private_file ✏️ · `