CSE MCP Server

@gajarthan/cse-mcp is a TypeScript Model Context Protocol server for the Colombo Stock Exchange. It gives MCP-compatible clients a clean way to search listed companies, fetch normalized single-stock quotes, and retrieve market-wide snapshots such as status, summary, top gainers, top losers, and index data. It is built for developers, analysts, and AI-tool builders who want fast access to CSE data through a stable MCP tool surface instead of scraping raw website responses inside prompts.

• Search listed CSE companies by symbol or company name using the local CSV catalog
• Fetch normalized stock quote data from companyInfoSummery
• Retrieve market-wide data from marketStatus, marketSummery, topGainers, topLooses, aspiData, and snpData
• Validate tool inputs before making upstream requests
• Normalize undocumented CSE payloads into AI-friendly JSON
• Use a dedicated service layer for CSE HTTP calls and thin MCP handlers
• Apply request timeout and basic retry handling for transient upstream failures
• Log only to stderr so stdout stays clean for MCP transport
• Stay compatible with MCP Inspector and local stdio-based MCP clients

• This project uses unofficial, reverse-engineered public endpoints exposed by https://www.cse.lk/api/. Response shapes may change without notice.
• Market data may be delayed, incomplete, or temporarily unavailable. Verify important figures against official sources before making financial decisions.
• This server makes outbound requests to the CSE website. Symbols and request payloads sent through tools are transmitted to that external service.
• This server does not require API keys and does not include built-in telemetry or analytics.
• Tool outputs are returned to the MCP client you connect it to. Treat client logs, transcripts, and tool approval history as potentially sensitive.
• The server currently supports local stdio transport only. It does not yet expose a remote HTTP or SSE MCP endpoint.

• Node.js 20 or newer
• npm 10 or newer
• Internet access to https://www.cse.lk
• An MCP client that supports local stdio servers

Build locally:

npm install
npm run build

Minimum local MCP config:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

If you are developing locally, MCP Inspector is the fastest smoke test:

npm run inspector

If the package is published to npm, the fastest install path becomes:

{
  "mcpServers": {
    "cse": {
      "command": "npx",
      "args": ["-y", "@gajarthan/cse-mcp"]
    }
  }
}

Use search_company to find John Keells Holdings, then call get_stock_quote for the correct symbol.

This server supports local stdio usage only. In most clients, you can configure it in one of two ways:

• local development mode: node C:/absolute/path/to/cse-mcp/dist/index.js
• published package mode: npx -y @gajarthan/cse-mcp

• Supported now: local stdio MCP clients that launch a process with command and args
• Not supported yet: remote-only MCP clients that require SSE or streaming HTTP transport

Claude Code documents MCP support and works well with local stdio servers.

Add the server directly:

claude mcp add-json cse "{\"type\":\"stdio\",\"command\":\"node\",\"args\":[\"C:/absolute/path/to/cse-mcp/dist/index.js\"]}"

Published-package variant:

claude mcp add-json cse "{\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"@gajarthan/cse-mcp\"]}"

Or use .mcp.json:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

If Claude Desktop is already configured, you can also import those MCP entries into Claude Code:

claude mcp add-from-claude-desktop

OpenAI documents MCP configuration in ~/.codex/config.toml, and the Codex CLI and IDE extension share it.

CLI setup:

codex mcp add cse -- node C:/absolute/path/to/cse-mcp/dist/index.js

Published-package CLI setup:

codex mcp add cse -- npx -y @gajarthan/cse-mcp

config.toml setup:

[mcp_servers.cse]
command = "node"
args = ["C:/absolute/path/to/cse-mcp/dist/index.js"]

Published-package config.toml setup:

[mcp_servers.cse]
command = "npx"
args = ["-y", "@gajarthan/cse-mcp"]

Cursor MCP support is version-dependent. In versions that support local MCP servers, use a config equivalent to:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

If the client supports npx, you can usually replace the command with:

{
  "mcpServers": {
    "cse": {
      "command": "npx",
      "args": ["-y", "@gajarthan/cse-mcp"]
    }
  }
}

Verify the exact config path and UI flow in your installed Cursor version.

VS Code and GitHub Copilot MCP support is version-dependent. In builds that support local MCP servers, the common pattern is a workspace or user mcp.json-style config using command and args:

{
  "servers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

Verify the exact file location and schema for your VS Code or Copilot version before relying on this example.

Cline MCP support is version-dependent. In versions that support local MCP stdio servers, use the same process-launch pattern:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

Verify the current config file name and location in the Cline docs or extension UI.

Continue support is version-dependent and may be configured through its YAML or UI-based MCP settings. The practical local setup is still the same:

mcpServers:
  cse:
    command: node
    args:
      - C:/absolute/path/to/cse-mcp/dist/index.js

Verify the current Continue config format for your installed version.

Roo Code MCP support is version-dependent. Use the same local stdio command pattern in the version-specific MCP settings:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

TODO: verify and document the exact current Roo Code config path.

Gemini CLI MCP support is version-dependent. For versions that support local MCP servers, configure this server as a local stdio process:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

Verify the current Gemini CLI config path and schema in the version you are using.

This project is intended for Smithery publishing through the GitHub repository integration path.

What is verified:

• The server is a local stdio MCP server
• The npm package is published as @gajarthan/cse-mcp
• The repository is public on GitHub

What is intentionally not supported today:

• public HTTPS MCP deployment
• SSE transport
• hosted remote MCP URL publishing

For Smithery, that means the practical route is to connect the GitHub repo and let Smithery build from the repository, branch, and base directory instead of requiring a public MCP URL.

Recommended Smithery settings for this repo:

• repository: Gajarthan/cse-mcp
• branch: master
• base directory: .
• auto deploy: enable only after the first successful publish

See SMITHERY.md for the full GitHub-to-Smithery workflow, checklists, and common failure points.

This repository already includes tag-driven release automation in .github/workflows/release.yml.

To create a GitHub release:

1. Update package.json, src/index.ts, server.json, and glama.json to the intended version
2. Add release notes to CHANGELOG.md
3. Run npm run release:check
4. Create and push a semver tag such as v2.0.1
5. Open the draft GitHub release created by Actions, review the generated notes, and publish it

The workflow validates the release on both Ubuntu and Windows before drafting the GitHub release.

Search the local CSV catalog by company name or ticker symbol.

Input:

{
  "query": "john keells"
}

Returns:

• normalized query
• ranked matches
• symbol, company name, and match score

Fetch a normalized quote for a valid CSE symbol.

Input:

{
  "symbol": "JKH.N0000"
}

Returns:

• last price and previous close
• price change and percentage change
• day range and 52-week range
• volume, turnover, market cap, and beta values
• source metadata and fetched timestamp

Fetch the current market session string from CSE and normalize it to a status plus inferred open/closed signal.

Input:

{}

Fetch market-wide turnover, share volume, trade count, and trade date.

Input:

{}

Fetch the top market gainers.

Input:

{
  "limit": 10
}

Notes:

• default limit is 10
• maximum limit is 25

Fetch the top market losers.

Input:

{
  "limit": 10
}

Notes:

• default limit is 10
• maximum limit is 25

Fetch one or both supported index summaries.

Input:

{
  "index": "all"
}

Allowed values:

• aspi
• snp
• all

• Transport: stdio only
• Required environment variables: none
• Required API keys: none
• Default upstream timeout: 10000ms
• Default retry count for transient failures: 2

This project does not currently expose custom CLI flags. Run it with:

node dist/index.js

This project does not currently require or document custom environment variables.

If timeout, retry count, base URL override, or CSV path override should become user-configurable, they should be added explicitly and documented here rather than inferred from source code.

• This server supports stdio transport only
• The upstream CSE API is unofficial and may change without notice
• Market data correctness and availability depend on the CSE website
• Hosted HTTP/SSE deployment is not implemented yet
• Smithery GitHub publishing is documentation-aligned here, but the final build behavior should still be verified in your Smithery project UI and deployment logs

• Make sure the client supports local stdio MCP servers
• Make sure the path in args is absolute
• Run npm run build before pointing the client at dist/index.js
• Restart the MCP client after changing config
• If you are using the npm package path, make sure npx @gajarthan/cse-mcp works from your terminal

Run the server directly to inspect stderr:

node dist/index.js

Check:

• Node.js version is 20 or newer
• dependencies are installed
• dist/index.js exists
• the client config uses the correct path separator and quoting for your OS

• Use search_company first to confirm the exact CSE symbol
• Symbols are validated against the bundled CSV catalog before quote calls
• If the symbol exists in CSE but not in the CSV, update cse_companies.csv

• The CSE API is unofficial and response shapes can change
• Retry a few minutes later to rule out transient issues
• Re-run with MCP Inspector or direct local execution to inspect stderr logs
• If the response shape changed, update the Zod parsing and normalization logic in src/services/cseApi.ts

That is expected for now. This server is stdio-only, while ChatGPT's documented remote MCP flow expects SSE or streaming HTTP.

Use an absolute path and forward slashes in JSON config when possible:

{
  "command": "node",
  "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
}

If you do not want to deal with local paths, prefer the published package form:

{
  "command": "npx",
  "args": ["-y", "@gajarthan/cse-mcp"]
}

If a client has trouble launching the package directly, use the explicit npm package form:

{
  "command": "npx",
  "args": ["-y", "-p", "@gajarthan/cse-mcp", "cse-mcp"]
}

Install and build:

npm install
npm run build

Useful scripts:

• npm run dev - watch-mode development with tsx
• npm run build - compile TypeScript to dist/
• npm run typecheck - run TypeScript checks without emitting files
• npm run start - start the compiled server
• npm run inspector - launch MCP Inspector against the local build
• npm run pack:check - verify npm package contents without publishing
• npm run release:check - run typecheck, build, tests, and npm pack validation

Recommended local workflow:

1. Run npm install
2. Run npm run typecheck
3. Run npm run build
4. Run npm run inspector
5. Test at least:
   • search_company
   • get_stock_quote
   • get_market_summary
   • get_index_summary

Project layout:

• src/index.ts - MCP server bootstrap and stdio transport
• src/services/companyLookup.ts - CSV-backed symbol and company search
• src/services/cseApi.ts - CSE API HTTP calls, validation, retries, and normalization
• src/tools/*.ts - individual MCP tool definitions
• src/utils/errors.ts - safe error handling and stderr logging
• src/utils/formatters.ts - output formatting and normalization helpers

See CHANGELOG.md.

This is an open source project, and contributions are welcome.

See CONTRIBUTING.md for local setup, validation steps, and pull request expectations.

Suggested contribution flow:

1. Fork the repository
2. Create a feature branch
3. Run npm install
4. Run npm run typecheck
5. Run npm run build
6. Test with MCP Inspector
7. Open a pull request with a clear summary

High-value contribution areas:

• new tools such as chartData, allSectors, and announcements
• stronger automated tests for normalization and error handling
• better handling of CSE response shape drift
• clearer client configuration docs as MCP client support evolves

If you discover a changed CSE response shape, include a sanitized example payload in the issue or PR whenever possible.