How do I use psx-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@psx-mcp List upcoming dividends with payout above 50%" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

psx-mcp

by revolutionarybukhari

Overview Schema Source Related Servers Score Discussions Admin

Python

Remote

psx-mcp

PyPI Python License MCP

mcp-name: io.github.revolutionarybukhari/psx-mcp

Talk to the Pakistan Stock Exchange in plain English.

psx-mcp is a Model Context Protocol server that exposes PSX market data — quotes, dividends, announcements, indices — as tools any MCP-compatible AI client can call. Connect it to Claude Desktop, Cursor, ChatGPT, or your own agent, and ask questions like:

"What are the upcoming dividends on PSX with payouts above 100%?"
"Should I buy MEBL today to collect the dividend?"
"Pull recent announcements for OGDC and summarize anything material."
"How has FFC's dividend history looked over the past 5 years?"

The LLM picks the right tools automatically and answers in your language.

Why MCP?

Existing PSX tools are libraries — you import them, write code, get data. MCP servers are tools an LLM calls for you. You ask in English, the model invokes get_quote, get_upcoming_dividends, get_dividend_history, and synthesizes an answer. No Python required for the end user.

This is also the first PSX MCP server published. If you're building agents, financial copilots, or AI-augmented research workflows for Pakistani markets, this gives them eyes.

Related MCP server: OpenInsider MCP

What's exposed

Tools (LLM-callable)

Tool	What it does
`get_quote(symbol)`	Current price snapshot for a symbol
`get_upcoming_dividends(symbol?)`	Payouts table, optionally filtered, with computed buy deadlines
`get_buy_deadline(symbol)`	Last day to buy and still collect the dividend (T+2 settlement)
`get_dividend_history(symbol, years)`	Historical payouts
`get_announcements(symbol?, limit)`	Recent corporate filings + PDF links
`search_symbols(query)`	Fuzzy match company names → tickers
`get_indices()`	KSE100, KSE30, KMI30, ALLSHR, PSXDIV20, etc.
`get_market_status()`	Is PSX open right now? When does it open next?
`screen_dividend_stocks(min_payout_pct)`	Filter upcoming dividends by payout size

Resources (read-only context)

psx://market-status
psx://indices
psx://upcoming-dividends

Prompts (templated workflows)

analyze_dividend_play(symbol) — full dividend-trade analysis
portfolio_review(symbols) — review a holdings list
find_dividend_opportunities(min_payout_pct) — screener + per-name analysis

Install

Requires Python 3.10+.

# From PyPI (once published)
pip install psx-mcp

# Or with uv (recommended)
uv tool install psx-mcp

# From source
git clone https://github.com/revolutionarybukhari/psx-mcp
cd psx-mcp
pip install -e .

Connect to Claude Desktop

Edit your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "psx": {
      "command": "uvx",
      "args": ["psx-mcp"]
    }
  }
}

Restart Claude Desktop. You should see the PSX tools listed in the connection icon. Try:

"What dividends are coming up this week on PSX?"

Connect to Cursor

Settings → MCP → add server:

{
  "mcpServers": {
    "psx": {
      "command": "psx-mcp",
      "args": []
    }
  }
}

Run as remote HTTP server

For shared/team use or hosted agents:

psx-mcp --transport http --host 0.0.0.0 --port 8000

The server is then reachable at http://localhost:8000/mcp. Test it with the MCP Inspector:

npx @modelcontextprotocol/inspector
# point it at http://localhost:8000/mcp

Example prompts to try

Once connected:

"List all PSX stocks paying more than 50% dividend right now,
sorted by buy deadline."

"For each stock in my portfolio (HBL, OGDC, PSO, ENGRO, MEBL),
tell me if there's an upcoming dividend and what the buy deadline is."

"Find me consistent dividend payers on PSX — companies that have
paid every year for the last 3+ years with payouts above 30%."

"What's happening with FFC today? Pull the quote and the latest
3 announcements."

"Walk me through the dividend trade for MARI step by step."

How it works

   ┌──────────────────────┐         ┌─────────────────┐
   │  Claude / Cursor /   │  MCP    │   psx-mcp       │
   │  ChatGPT / Agent     │ ──────► │   server        │
   └──────────────────────┘         └────────┬────────┘
                                             │ httpx + bs4
                                             ▼
                                    ┌─────────────────┐
                                    │ dps.psx.com.pk  │
                                    └─────────────────┘

Tools call the public PSX Data Portal, parse HTML with BeautifulSoup, normalize into structured JSON, and return to the LLM. No keys, no auth, no scraping headaches for the consumer.

Architecture notes

Async everywhere. All scraper functions use httpx.AsyncClient so MCP calls don't block.
Symbol cache. The full PSX symbol list is cached for 24h to make search_symbols fast.
Trading-day math. Buy-deadline calculation uses BC_From − 2 trading days, skipping weekends and configurable holidays in dividend_calc.PSX_HOLIDAYS_2026.
No persistence. This server is stateless. State (alerts, watchlists) belongs in your client.

Pairs well with

This is one server in a wider PSX open-source toolkit:

psx-dividend-alert — proactive Telegram alerts for upcoming dividends
psx-cgt-calculator — Pakistan capital-gains-tax with FIFO lots
psx-zakat-calculator — zakat on stock holdings (zakatable assets method)
psx-broker-statement-parser — normalize KTrade/AKD/JS Global PDFs
psx-announcements-summarizer — LLM-powered summaries of every PSX filing

The MCP server makes all of these LLM-callable. Pair them and you have a complete conversational PSX research stack.

Limitations / honest notes

PSX data is delayed ~5 minutes. Same as the public Data Portal.
Scraping is fragile. If PSX changes their HTML, parsers will need updating. PRs welcome.
No order placement. This is read-only. There's no path here that puts trades on the wire — by design.
Holiday list is stub. Edit PSX_HOLIDAYS_2026 in dividend_calc.py once PSX publishes the annual calendar. Without it, the buy-deadline math correctly skips weekends but will be off during Eid/Independence Day weeks.
Personal use. PSX terms restrict commercial redistribution of market data without a license. Email marketdatarequest@psx.com.pk if you need one.

Contributing

Add a tool: write the function in scraper.py, expose it in server.py with @mcp.tool(), add a docstring (the docstring becomes the LLM's tool description — make it clear).
Add a test: drop async tests in tests/. The MCP SDK supports in-memory testing.
File issues for HTML parser breakage with the failing URL and a snippet.

License

MIT. See LICENSE.

Available Tools

9 tools

get_announcementsA

Get recent corporate announcements from PSX.

Args: symbol: Optional ticker filter (e.g. only OGDC announcements). limit: Max rows to return (default 20, cap 100).

Each item includes date, symbol, title, and a PDF link to the original notice.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`symbol`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It mentions the limit cap (100) but does not disclose other behaviors such as rate limits, authentication requirements, or that it is a read-only operation. Adequate but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a one-sentence purpose, followed by bullet-like parameter descriptions, and a note on output content. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with two optional parameters and an existing output schema. The description covers the output fields and parameter defaults. Minor gaps: no mention of ordering (e.g., most recent first) or error scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the description fully compensates: it explains 'symbol' as a ticker filter (e.g., OGDC) and 'limit' with default 20 and cap 100, adding meaning beyond the schema's titles and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get recent corporate announcements from PSX,' specifying the verb, resource, and scope. It distinguishes from sibling tools like get_quote and get_dividend_history by focusing on announcements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives. It only describes optional parameters without stating when not to use it or suggesting other tools for different needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_buy_deadlineA

For a symbol with an upcoming dividend, return the last day you can buy and still be entitled to the dividend (T+2 settlement applied).

Returns 'no upcoming dividend' if the symbol isn't currently in the PSX payouts table.

ParametersJSON Schema

Name	Required	Description	Default
`symbol`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the T+2 settlement rule and the special return string. It does not specify output format (e.g., date format) but adequately conveys the behavior for a simple query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main purpose, and includes the alternative outcome. No extraneous words; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description covers core functionality and edge case. It could specify the output format (e.g., date string) but is otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'symbol' is implied in the description as a stock ticker. The description adds meaning by explaining it must be in the PSX payouts table. With 0% schema coverage, the description compensates well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the last buy date for a symbol with an upcoming dividend, applying T+2 settlement. The verb 'return' and resource 'buy deadline' are specific, and the tool is well-distinguished from siblings like get_upcoming_dividends and get_dividend_history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies the tool is for symbols with upcoming dividends and details the 'no upcoming dividend' case. However, it does not explicitly contrast with siblings like get_dividend_history or screen_dividend_stocks, leaving some implicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_dividend_historyA

Get historical dividend payouts for a symbol.

Args: symbol: PSX ticker. years: How many years of history to return (default 5).

ParametersJSON Schema

Name	Required	Description	Default
`years`	No
`symbol`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It correctly indicates a read operation (getting history) with no mention of destructive effects. Missing details on rate limits, error handling, or auth requirements, but acceptable for a simple read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (three lines) with no fluff. Purpose is front-loaded, and parameter details follow in a clean docstring format.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has an output schema (context signal true), so description need not explain return value. Parameter coverage is adequate. With siblings listed, the tool's role is clear. Minor gap: no mention of default year behavior or error cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description adds vital meaning: 'symbol' is a PSX ticker and 'years' is how many years of history with default 5. This goes beyond the schema's bare types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves historical dividend payouts for a symbol, using specific verb 'Get' and resource 'historical dividend payouts'. It distinguishes from sibling tools like get_upcoming_dividends (future dividends) and get_quote (current price).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides basic context: symbol is a PSX ticker and years defaults to 5. However, it does not specify when to use this tool versus siblings (e.g., get_upcoming_dividends for future payouts) or any prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_indicesA

Get current values for major PSX indices: KSE100, KSE30, ALLSHR, KMI30, KMIALLSHR, PSXDIV20, BKTI, OGTI, MII30.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden. It states it gets current values, which is a simple read operation, but provides no details on side effects, authentication, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, front-loading the action and listing indices in one sentence with no extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and presence of an output schema, the description is complete: it fully explains the tool's purpose and scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description needs only to explain what is returned. It lists all indices, adding value beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves current values for major PSX indices and explicitly names eight specific indices, distinguishing it from sibling tools that handle announcements, dividends, quotes, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for PSX index data by listing indices, but offers no explicit guidance on when to use or avoid this tool, nor does it mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_market_statusA

Is PSX open right now? Returns OPEN / PRE_OPEN / CLOSED_TODAY / WEEKEND plus the next market open in PKT.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It discloses the return values (enum-like) and timezone (PKT). It could mention it's a non-destructive read, but overall clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with the key question, zero waste. Perfectly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description fully explains return values (status enum and next open time). Complete for a simple status-check tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so the description need not add parameter info. Schema coverage is 100% (empty). A baseline of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states what the tool does: returns PSX market status (OPEN/PRE_OPEN/CLOSED_TODAY/WEEKEND) and next open time. It distinguishes from sibling tools like get_quote or get_indices by focusing on market hours.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking if PSX is open ('Is PSX open right now?'), but provides no explicit when-to-use or when-not-to-use guidance, nor mentions alternatives among sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_quoteA

Get the current price quote for a PSX-listed symbol.

Args: symbol: PSX ticker, e.g. "MEBL", "OGDC", "FFC", "ENGRO".

Returns last price, change, change %, volume, day high/low, open, prev close. Data is delayed by 5 minutes per PSX Data Portal.

ParametersJSON Schema

Name	Required	Description	Default
`symbol`	Yes

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided; the description carries full burden. It discloses a 5-minute data delay and explains the return fields (last price, change, volume, etc.), giving a complete picture of behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with four clear sentences covering purpose, parameters, returns, and note. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no nested objects), the description fully covers parameter usage, return details, and data delay. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0% description coverage, but the description defines the 'symbol' parameter with concrete examples (e.g., 'MEBL', 'OGDC'). This adds essential meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a current price quote for a PSX-listed symbol, specifying the resource and scope. It distinguishes from siblings like get_indices and get_market_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage with examples (e.g., 'MEBL', 'OGDC') and context (PSX). It lacks explicit when-not-to-use or alternative tools, but the context is sufficient for correct selection among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_upcoming_dividendsA

List upcoming dividend payouts on PSX.

Args: symbol: Optional PSX ticker to filter. If omitted, returns all upcoming payouts in the table.

Each result includes book closure dates, AGM date, payout amount/type, and the computed buy deadline (T+2 settlement) — the last day you can buy and still be entitled to the dividend.

ParametersJSON Schema

Name	Required	Description	Default
`symbol`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It transparently discloses that the tool returns a list of payouts, including specific fields (book closure, AGM date, payout amount/type, buy deadline) and the optional filtering behavior. No hidden side effects or destructive actions are indicated, and the description appears accurate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences plus a bullet-like list of result fields. Every sentence adds value without repetition, and the structure is clear and front-loaded with the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential behavior (listing upcoming dividends, filtering by symbol) and enumerates the key return fields. With an output schema present (per context signals), avoiding detailed return format is acceptable. It could explicitly note that only future payouts are returned, but 'upcoming' implies this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description must compensate. It explains the 'symbol' parameter succinctly: 'Optional PSX ticker to filter. If omitted, returns all upcoming payouts in the table.' This provides clear meaning beyond the raw schema definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List upcoming dividend payouts on PSX,' specifying a concrete verb, resource, and market. The additional detail about results including book closure dates, AGM date, payout amount/type, and buy deadline further clarifies the tool's purpose and distinguishes it from siblings like get_dividend_history (past payouts) and get_buy_deadline (computing a single deadline).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the optional symbol filter and its effect ('If omitted, returns all upcoming payouts'), but does not explicitly state when to use this tool versus alternatives like get_quote or screen_dividend_stocks. Usage context is implied but lacks explicit when-to-use/when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

screen_dividend_stocksA

Screen the upcoming-payouts table by payout size.

Args: min_payout_pct: Minimum payout % to include (e.g. 50 = 50% of par). PSX payouts are quoted as % of face value (typically Rs 10). limit: Max results.

NOTE: This is a payout-size filter, not a true dividend-yield screen (yield = dividend / current price). For real yield you'd cross-reference each symbol's current price — call get_quote() per symbol if needed.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`min_payout_pct`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that the tool filters by payout size, not yield, which is a key behavioral trait. It also explains the parameter semantics. However, it does not mention authorization needs, rate limits, or potential side effects, which would be useful but not critical for a screening tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: one sentence stating the purpose plus a short clarifying note. Every sentence earns its place, with no superfluous text. The key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 parameters, output schema present), the description is complete. It explains what the tool does, how to use the parameters, and a critical behavioral caveat. The output schema covers return values, so no further detail needed. No obvious gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description compensates for the 0% schema coverage by fully explaining both parameters. For min_payout_pct, it gives a concrete example (50 = 50% of par) and context (PSX payouts quoted as % of face value). For limit, it says 'Max results'. This adds significant value beyond the schema's bare types and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool screens the 'upcoming-payouts table' by payout size, with the verb 'screen' and resource clearly identified. It distinguishes from sibling tools like get_upcoming_dividends (which likely lists all) and get_dividend_history (historical), and explicitly notes it's not a true yield screen, avoiding confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the tool's purpose and includes a note clarifying when not to use it (for true yield) and suggests an alternative (get_quote). However, it does not explicitly compare with closely related siblings like get_upcoming_dividends, leaving some ambiguity about when to prefer this tool over others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_symbolsA

Fuzzy search PSX symbols and company names.

Useful when the user names a company casually ("habib bank" -> "HBL", "fauji fertilizer" -> "FFC").

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. Mentions 'fuzzy search' but does not detail behavior like ranking, number of results, or whether it searches exact names. Adds some value but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, zero wasted words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Has output schema so return values need not be explained. Description provides a useful example but could elaborate on fuzzy matching behavior or search scope. Overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It does not mention parameters at all. Schema shows query and limit clearly, but description adds no extra meaning beyond what schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Fuzzy search PSX symbols and company names', specifying the verb 'search', the resource 'PSX symbols and company names', and the method 'fuzzy'. It distinguishes from siblings which are about announcements, dividends, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a concrete example ('habib bank' -> 'HBL') indicating when to use: when user names a company casually. No explicit when-not or alternatives, but sibling tools are clearly different so guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

9 tool updatesv0.1.1Jul 5, 2026
- First observedget_announcements
- First observedget_buy_deadline
- First observedget_dividend_history
- First observedget_indices
- First observedget_market_status
- First observedget_quote
- First observedget_upcoming_dividends
- First observedscreen_dividend_stocks
- First observedsearch_symbols

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored 2026-07-05 16:35 across 9 tools

Disambiguation5/5

Each tool targets a distinct aspect of PSX data: announcements, dividends (various forms), indices, market status, quotes, and symbol search. No two tools have overlapping purposes.

Naming Consistency4/5

Most tools follow a 'get_' prefix (get_announcements, get_quote, etc.), but 'screen_dividend_stocks' and 'search_symbols' use different verbs. The pattern is mostly consistent with minor deviations.

Tool Count5/5

Nine tools is well-scoped for a stock exchange data server, covering essential functions without being overly numerous or sparse.

Completeness4/5

The tool set covers quotes, indices, market status, dividends (history, upcoming, screening, buy deadline), announcements, and symbol search. Missing historical prices or detailed corporate actions, but adequate for typical queries.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Backtest360 A
com.backtest360
MCP server exposing the Backtest360 engine API as tools for AI agents.
Finance Research & Data
202
openmm-mcp A
io.github.QBT-Labs
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
Finance
1513
china-market-intelligence-mcpOAuth
com.thenextgennexus
MCP server giving AI agents one-connection access to China A-share market intelligence: financials,
Finance Research & Data
2
UnifAPIOAuth
com.unifapi
Hosted MCP server for live public-data APIs and Skills for AI agents.
Open Data Search AI & Machine Learning
2

Related MCP Servers

Alpaca MCP Server
Finance Databases Cloud Platforms
cesarvarela
A
license
D
quality
D
maintenance
MCP server that exposes Alpaca Market Data & Broker API as tools, enabling access to financial data like stock bars, assets, market days, and news through the Message Control Protocol.
Updated a year ago (2025-06-01 01:49 UTC)
4
40
2
ISC
OpenInsider MCP
Finance Research & Data
btopn
A
license
Not graded
quality
A
maintenance
An MCP server that exposes 16 free investment-research signals (insider trades, SEC filings, short data, and live quotes) to any MCP-compatible LLM.
Updated a month ago (2026-08-07 15:13 UTC)
36
98
MIT
financial-research-agent
Finance AI & Machine Learning
rahul-jajala
F
license
Not graded
quality
D
maintenance
MCP server that exposes stock research tools (fundamentals, news, technicals, analyst ratings) to AI clients, enabling autonomous generation of structured investment briefs.
Updated 3 months ago (2026-06-09 22:20 UTC)
-
siftingio-mcpofficial
Finance Cryptocurrency
SiftingIO
A
license
A
quality
C
maintenance
MCP server that provides access to SiftingIO market data, including live prices, SEC filings, OHLCV bars, 13F holdings, market status, and economic calendar tools for AI assistants.
Updated 2 months ago (2026-07-11 12:34 UTC)
36
43
1
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/revolutionarybukhari/psx-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

psx-mcp

Why MCP?

What's exposed

Tools (LLM-callable)

Resources (read-only context)

Prompts (templated workflows)

Install

Connect to Claude Desktop

Connect to Cursor

Run as remote HTTP server

Example prompts to try

How it works

Architecture notes

Pairs well with

Limitations / honest notes

Contributing

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

siftingio-mcpofficial

Latest Blog Posts

MCP directory API