@gajarthan/cse-mcp

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.

Key Features

• 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

Disclaimers, Security, and Privacy

• 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.

Requirements

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

Getting Started

Use a local build

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

Use the published npm package

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

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

First test prompt

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

MCP Client Configuration

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 @gajarthan/cse-mcp

Local stdio vs remote HTTP

• 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

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\":[\"@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

Codex

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 @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 = ["@gajarthan/cse-mcp"]

Cursor

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": ["@gajarthan/cse-mcp"]
    }
  }
}

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

VS Code / Copilot

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

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

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

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

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.

Tool Reference

search_company

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

get_stock_quote

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

get_market_status

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

Input:

{}

get_market_summary

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

Input:

{}

get_top_gainers

Fetch the top market gainers.

Input:

{
  "limit": 10
}

Notes:

• default limit is 10
• maximum limit is 25

get_top_losers

Fetch the top market losers.

Input:

{
  "limit": 10
}

Notes:

• default limit is 10
• maximum limit is 25

get_index_summary

Fetch one or both supported index summaries.

Input:

{
  "index": "all"
}

Allowed values:

• aspi
• snp
• all

Configuration, Flags, and Environment Variables

Current runtime configuration

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

CLI flags

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

node dist/index.js

Environment variables

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

TODO

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.

Troubleshooting

The client shows no tools

• 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

The server fails to start

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

Quote lookup fails for a symbol

• 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

Upstream timeouts or unexpected response errors

• 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

ChatGPT does not connect to this server

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

Windows path issues

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": ["@gajarthan/cse-mcp"]
}

Development

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

Recommended local workflow:

• Run npm install
• Run npm run typecheck
• Run npm run build
• Run npm run inspector
• 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

Changelog

Formal changelog management is not set up yet.

TODO:

• add a CHANGELOG.md
• tag releases consistently
• document breaking changes in tool contracts

Contributing

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

Suggested contribution flow:

• Fork the repository
• Create a feature branch
• Run npm install
• Run npm run typecheck
• Run npm run build
• Test with MCP Inspector
• 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.