Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@RS.ge Waybill MCP Server show me waybills from last week"
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.
MCP (Model Context Protocol) server that integrates the RS.ge Waybill SOAP API with Claude Desktop, enabling natural language queries for Georgian tax system waybills.
Related MCP server: rs-mcp
# 1. Install dependencies
npm install
# 2. Configure credentials
cp .env.example .env
# Edit .env with your RS.ge credentials
# 3. Build
npm run build
# 4. Configure Claude Desktop
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
# Add to config:
{
"mcpServers": {
"rs-waybill": {
"command": "node",
"args": ["ABSOLUTE_PATH_TO_PROJECT/dist/index.js"]
}
}
}
# 5. Restart Claude Desktop
# 6. Test in Claude
"Show me waybills from October 19-21, 2025"β Natural Language Interface - Query waybills through Claude chat
β Date Range Queries - Get waybills for specific periods
β TIN Lookup - Get company names from Tax IDs
β Dictionaries - Access error codes, akciz codes, waybill types
β Type-Safe - Full TypeScript with strict typing
β Error Handling - Automatic retries and detailed logging
β Production Ready - Tested with real RS.ge API
Comprehensive guides in the docs/ folder:
Setup & Deployment Guide - Installation, configuration, troubleshooting
Project Documentation - Architecture, components, data flow
RS.ge API Best Practices - Critical lessons learned and correct API patterns
MCP Development Guide - How to build MCP servers
Get the Code
git clone <repository-url> MCPWaybill
cd MCPWaybillInstall Dependencies
npm installConfigure Environment
cp .env.example .envEdit .env:
RS_SERVICE_USER=4053098841:405309884
RS_SERVICE_PASSWORD=YourPasswordHereBuild
npm run buildConfigure Claude Desktop
Edit claude_desktop_config.json:
{
"mcpServers": {
"rs-waybill": {
"command": "node",
"args": [
"C:\absolute\path\to\MCPWaybill\dist\index.js"
]
}
}
}β οΈ Important: Use absolute paths!
Restart Claude Desktop (quit completely, then restart)
Create .env file:
# Required
RS_SERVICE_USER=username:company_id
RS_SERVICE_PASSWORD=your_password
# Optional
LOG_LEVEL=infoEdit config/config.json for advanced settings:
{
"api": {
"timeout": 30000,
"retries": 3
},
"logging": {
"level": "info",
"console": true
}
}User: Show me waybills from October 19-21, 2025
Claude: I'll retrieve those waybills for you.
[Uses rs_get_waybills tool]
Found 61 waybills:
- October 19: 12 waybills
- October 20: 32 waybills
- October 21: 17 waybills
...User: What company has TIN 405309884?
Claude: [Uses rs_lookup_tin tool]
Company: α¨αα‘ αααα‘ααUser: Show me RS.ge error codes
Claude: [Uses rs_get_error_codes tool]
Error codes:
- -1072: Date range issue
- -101: Missing seller_un_id
...Check absolute path in claude_desktop_config.json
Verify dist/index.js exists
Restart Claude Desktop completely
Check Developer Tools (View β Toggle Developer Tools)
Verify credentials in .env
Check format: username:company_id
Ensure no spaces: RS_SERVICE_USER=value (not RS_SERVICE_USER = value)
Check logs: tail -f logs/mcp-server.log
Test with: "Show waybills from yesterday"
Verify date format: YYYY-MM-DD
See Troubleshooting Guide for detailed help.
npm run build # Compile TypeScript
npm run dev # Build and run
npm run watch # Auto-rebuild on changessrc/
βββ index.ts # MCP server entry point
βββ config/ # Configuration management
βββ services/ # RS.ge API client & XML parsing
β βββ soap-client.ts # SOAP API client
β βββ xml-parser.ts # XML handling
βββ tools/ # MCP tools
β βββ get-waybills.ts
β βββ get-dictionaries.ts
β βββ lookup-tin.ts
βββ types/ # TypeScript types
βββ utils/ # Utilities@modelcontextprotocol/sdk - MCP framework
Axios - HTTP client
fast-xml-parser - XML parsing
Winston - Logging
Zod - Validation
This project solved complex RS.ge API integration challenges:
Aspect | β Wrong | β Correct |
Operation |
|
|
Date Param |
|
|
Date Format |
|
|
End Date | As-is | Add +1 day |
Seller ID | Not included | Extract from credentials |
ID Field |
|
|
Filter out @_ attributes before extracting data
Handle both single and array responses
See RS_GE_API_BEST_PRACTICES.md for complete details.
MIT License - See LICENSE file for details
Fork the repository
Create feature branch
Make changes
Test thoroughly
Submit pull request
Documentation: docs/
Issues: GitHub Issues
Questions: Check docs first
Anthropic - Claude Desktop and MCP SDK
RS.ge - Waybill SOAP API
Community - Testing and feedback
Version: 1.0.0
Status: Production Ready β
Last Updated: January 2025
Built with β€οΈ using TypeScript and MCP SDK
Get akciz (excise) codes from RS.ge system. Optionally filter by search text.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Optional search text to filter results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Get[s] akciz (excise) codes,' implying a read-only operation, but doesn't disclose critical behavioral traits such as whether it requires authentication, rate limits, pagination, error handling, or what the return format looks like (e.g., list of objects). This leaves significant gaps for an AI agent to understand how to use it effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: it starts with the core purpose and immediately follows with the optional filtering feature. Both sentences earn their place by providing essential information without redundancy or fluff, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a tool with one parameter. It doesn't explain what the tool returns (e.g., structure of akciz codes, error responses), behavioral aspects like authentication needs, or how it differs from sibling tools. This leaves the AI agent with insufficient context to use the tool correctly beyond basic retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal value beyond the input schema, which has 100% coverage. It mentions 'Optionally filter by search text,' aligning with the schema's 'search' parameter description ('Optional search text to filter results'). No additional semantic details (e.g., search syntax, case sensitivity) are provided. With high schema coverage, the baseline is 3, as the description doesn't compensate with extra insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get akciz (excise) codes from RS.ge system.' It specifies the verb ('Get'), resource ('akciz codes'), and source ('RS.ge system'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_error_codes' or 'lookup_tin', which prevents a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance by mentioning 'Optionally filter by search text,' suggesting this tool is for retrieving codes with optional filtering. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., 'get_error_codes' or 'lookup_tin'), no exclusions, and no clear context for choosing among siblings, resulting in a moderate score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all error codes and their descriptions from RS.ge system
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it 'gets' data (implying a read operation) but doesn't mention any behavioral traits like rate limits, authentication needs, response format, or whether it returns all codes at once or supports pagination. This leaves significant gaps for a tool that fetches system data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any fluff or redundant information. It's appropriately sized and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a data-fetching tool. It doesn't explain what the return values look like (e.g., list format, fields included), behavioral constraints, or how it fits with sibling tools, leaving the agent with insufficient context to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, earning a baseline score of 4 for not adding unnecessary information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('all error codes and their descriptions from RS.ge system'), making the purpose unambiguous. However, it doesn't differentiate this tool from its siblings (like get_akciz_codes or get_waybills), which appear to fetch different types of codes/documents from the same system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for fetching error codes, or how it differs from sibling tools like get_akciz_codes or lookup_tin, leaving the agent with no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get waybills from RS.ge for a specific date range. Returns all waybills created within the specified dates. Can optionally filter by buyer TIN.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | Start date in YYYY-MM-DD format (e.g., "2025-10-17") | |
| end_date | Yes | End date in YYYY-MM-DD format (e.g., "2025-10-20") | |
| buyer_tin | No | Optional: Filter by buyer TIN (tax identification number) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions what the tool returns ('all waybills created within the specified dates') but lacks details on permissions, rate limits, pagination, error handling, or response format. For a read operation with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with two sentences that efficiently convey the core functionality and optional filtering. Every sentence earns its place without redundancy or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a read operation with date range and optional filtering), lack of annotations, and no output schema, the description is incomplete. It doesn't explain the return values, format, or behavioral aspects like pagination or errors, which are crucial for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds marginal value by reiterating the optional filter for buyer TIN, but it doesn't provide additional semantics beyond what's in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('waybills from RS.ge'), and it specifies the scope ('for a specific date range'). However, it doesn't explicitly distinguish this tool from its siblings (e.g., get_waybill_types), which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning 'for a specific date range' and 'can optionally filter by buyer TIN', but it doesn't provide explicit guidance on when to use this tool versus alternatives like get_waybill_types or lookup_tin. No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all available waybill types from RS.ge system
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states what the tool does without disclosing behavioral traits like whether it's read-only, requires authentication, has rate limits, or returns structured data. It mentions 'from RS.ge system' but doesn't explain system-specific behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and resource. There is no wasted text, making it highly concise and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but minimal. It covers the basic purpose but lacks context on usage, behavior, or output, leaving gaps for an agent to infer details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't add parameter details, maintaining focus on the tool's purpose without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('all available waybill types from RS.ge system'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_waybills' beyond the resource type, missing explicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_waybills' or other sibling tools. The description implies usage for retrieving waybill types but lacks context on prerequisites, exclusions, or specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a company or person name from their TIN (Tax Identification Number) in the RS.ge system.
| Name | Required | Description | Default |
|---|---|---|---|
| tin | Yes | Tax identification number (TIN) - 9 to 11 digits |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it indicates this is a lookup operation (implying read-only), it doesn't describe authentication requirements, rate limits, error conditions, response format, or whether the data is authoritative. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core purpose without any wasted words. It is appropriately sized and front-loaded, making it easy for an agent to quickly understand the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (single parameter lookup), 100% schema coverage, and no output schema, the description is minimally adequate. It explains what the tool does but lacks details on behavioral aspects like response format or error handling, which would be helpful for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'tin' fully documented in the schema (including type, description, and length constraints). The description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Look up'), the target resource ('a company or person name'), the input source ('from their TIN'), and the system context ('in the RS.ge system'). It distinguishes this tool from sibling tools like 'get_akciz_codes' or 'get_waybills' by focusing on TIN-based entity lookup rather than code retrieval or document fetching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, prerequisites for usage, or any exclusions. It states what the tool does but offers no context about appropriate scenarios, limitations, or how it relates to other tools in the system.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose targeting different resources or actions in the RS.ge system: retrieving excise codes, error codes, waybills, waybill types, and TIN lookups. There is no overlap in functionality, making it easy for an agent to select the correct tool without confusion.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., get_akciz_codes, get_error_codes, get_waybills, get_waybill_types, lookup_tin). The verbs 'get' and 'lookup' are appropriately chosen for their actions, maintaining predictability and readability throughout the set.
With 5 tools, the server is well-scoped for its purpose of interacting with the RS.ge waybill system. Each tool serves a specific, necessary function without redundancy, making the count appropriate for the domain and avoiding either excessive or insufficient coverage.
The tool set provides comprehensive read operations for the RS.ge domain, covering key resources like waybills, codes, and TIN lookups. A minor gap exists in the lack of write operations (e.g., creating or updating waybills), but agents can still perform essential retrieval tasks effectively.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Ecuador factura electronica for AI agents - issue and query SRI e-invoices via Datil. Stateless BYO.
Chile DTE for AI agents - boleta/factura electronica via OpenFactura or LibreDTE. Stateless BYO.
Peru CPE invoices for AI agents - issue, query, void facturas/boletas via SUNAT (2 backends).
Emite facturas, notas y retenciones del SRI de Ecuador con lenguaje natural.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/BorisSolomonia/MCPWaybill'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
