Connect RiceVarMap to your agent

Query rice variants, genes and cultivars through a local MCP server backed by the public v3 REST API.

Download MCP package

Quick start

Transport
stdio
Runtime
Python 3.10+
Data
RiceVarMap v3 REST API

Install the client

Download and extract the ZIP. Run these commands in the extracted ricevarmap-mcp directory.

Terminal · Linux / WSL
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Configure your agent

This example uses the mcpServers configuration format. Adapt the entry to your stdio-capable client. Replace the two absolute paths with the interpreter and server paths in your extracted directory.

Client configuration · JSON
{
  "mcpServers": {
    "ricevarmap-v3": {
      "command": "/absolute/path/to/ricevarmap-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/ricevarmap-mcp/server.py"]
    }
  }
}
Connect from a Windows client through WSL

Install the package inside WSL and use the matching distribution name and Linux paths.

Windows → WSL · JSON
{
  "mcpServers": {
    "ricevarmap-v3": {
      "command": "C:\\Windows\\System32\\wsl.exe",
      "args": [
        "--distribution",
        "Ubuntu",
        "--exec",
        "/home/your-user/ricevarmap-mcp/.venv/bin/python",
        "/home/your-user/ricevarmap-mcp/server.py"
      ]
    }
  }
}

The package reads the public API. Your agent supplies its own language model. The stdio process is started by your MCP client.

Check the connection

The included Python SDK client discovers the tools and runs the three examples below.

Terminal · Linux / WSL
.venv/bin/python example_client.py

Default API base https://ricevarmap.ncpgr.cn/v3/api/. Set RICEVARMAP_API_BASE_URL when using your own compatible backend.

Available tools

ToolUseArguments
get_variant_frequency Read details and allele frequency for one variant and one population. var_id population
list_gene_variants Page through variants in one explicit gene body and its requested flanks in bp. gene_id population up down limit offset
list_region_variants Page through all variant types in one explicit interval with a span of at most 100000 bp. reference chr start end population limit offset
query_genotypes Read raw and imputed genotype calls for 1 to 5 distinct vg IDs and 1 to 5 distinct cultivar IDs. var_ids cultivars
search_cultivars Find cultivar IDs by name or ID. Return up to ten matches with name, population and origin. q
get_cached_mapping Read cached cross-reference mappings for one variant ID without running an alignment. var_id
get_variant_frequency · parameters and schema
Discovered MCP input schema
{
  "properties": {
    "var_id": {
      "description": "RiceVarMap variant ID, such as vg0100001306.",
      "title": "Var Id",
      "type": "string"
    },
    "population": {
      "description": "Exact population code from the v3 population catalogue.",
      "title": "Population",
      "type": "string"
    }
  },
  "required": [
    "var_id",
    "population"
  ],
  "title": "get_variant_frequencyArguments",
  "type": "object"
}
list_gene_variants · parameters and schema
Discovered MCP input schema
{
  "properties": {
    "gene_id": {
      "maxLength": 100,
      "pattern": "^(?:LOC_Os|OsMH|OsZS|Os)[A-Za-z0-9_.-]+$",
      "title": "Gene Id",
      "type": "string"
    },
    "population": {
      "default": "All",
      "description": "Exact population code from the v3 population catalogue.",
      "title": "Population",
      "type": "string"
    },
    "up": {
      "default": 0,
      "maximum": 10000,
      "minimum": 0,
      "title": "Up",
      "type": "integer"
    },
    "down": {
      "default": 0,
      "maximum": 10000,
      "minimum": 0,
      "title": "Down",
      "type": "integer"
    },
    "limit": {
      "default": 5,
      "maximum": 1000,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "required": [
    "gene_id"
  ],
  "title": "list_gene_variantsArguments",
  "type": "object"
}
list_region_variants · parameters and schema
Discovered MCP input schema
{
  "properties": {
    "reference": {
      "enum": [
        "NIP",
        "MH63",
        "ZS97"
      ],
      "title": "Reference",
      "type": "string"
    },
    "chr": {
      "pattern": "^chr(?:0[1-9]|1[0-2])$",
      "title": "Chr",
      "type": "string"
    },
    "start": {
      "minimum": 1,
      "title": "Start",
      "type": "integer"
    },
    "end": {
      "minimum": 1,
      "title": "End",
      "type": "integer"
    },
    "population": {
      "default": "All",
      "description": "Exact population code from the v3 population catalogue.",
      "title": "Population",
      "type": "string"
    },
    "limit": {
      "default": 5,
      "maximum": 1000,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "required": [
    "reference",
    "chr",
    "start",
    "end"
  ],
  "title": "list_region_variantsArguments",
  "type": "object"
}
query_genotypes · parameters and schema
Discovered MCP input schema
{
  "properties": {
    "var_ids": {
      "items": {
        "pattern": "^vg(?:0[1-9]|1[0-2])[0-9]{8}$",
        "type": "string"
      },
      "maxItems": 5,
      "minItems": 1,
      "title": "Var Ids",
      "type": "array"
    },
    "cultivars": {
      "items": {
        "description": "Exact cultivar ID, such as B001 or IRIS_313-10009.",
        "type": "string"
      },
      "maxItems": 5,
      "minItems": 1,
      "title": "Cultivars",
      "type": "array"
    }
  },
  "required": [
    "var_ids",
    "cultivars"
  ],
  "title": "query_genotypesArguments",
  "type": "object"
}
search_cultivars · parameters and schema
Discovered MCP input schema
{
  "properties": {
    "q": {
      "maxLength": 80,
      "minLength": 1,
      "title": "Q",
      "type": "string"
    }
  },
  "required": [
    "q"
  ],
  "title": "search_cultivarsArguments",
  "type": "object"
}
get_cached_mapping · parameters and schema
Discovered MCP input schema
{
  "properties": {
    "var_id": {
      "description": "RiceVarMap variant ID, such as vg0100001306.",
      "title": "Var Id",
      "type": "string"
    }
  },
  "required": [
    "var_id"
  ],
  "title": "get_cached_mappingArguments",
  "type": "object"
}

Real examples

Each example shows the request, the follow-up context and a shortened result from the public API.

Verified snapshot · 2026-11-19T14:31:12Z

Compare allele frequency across populations

Keep the variant fixed and change the population code in each call. The returned rates are fractions.

What is the frequency of vg0100001306 in All? Then check IndII and VI.

Check vg0100001306 in All.

get_variant_frequency
{
  "name": "get_variant_frequency",
  "arguments": {
    "var_id": "vg0100001306",
    "population": "All"
  }
}
View verified result
Shortened result
{
  "var_id": "vg0100001306",
  "frequency": {
    "population": "All",
    "major_genotype": "G",
    "minor_genotype": "A",
    "major_rate": 0.984,
    "minor_rate": 0.015,
    "count": 4726
  }
}

Source · RiceVarMap REST response

Check vg0100001306 in IndII.

get_variant_frequency
{
  "name": "get_variant_frequency",
  "arguments": {
    "var_id": "vg0100001306",
    "population": "IndII"
  }
}
View verified result
Shortened result
{
  "var_id": "vg0100001306",
  "frequency": {
    "population": "IndII",
    "major_genotype": "G",
    "minor_genotype": "A",
    "major_rate": 1.0,
    "minor_rate": 0.0,
    "count": 465
  }
}

Source · RiceVarMap REST response

Check vg0100001306 in VI.

get_variant_frequency
{
  "name": "get_variant_frequency",
  "arguments": {
    "var_id": "vg0100001306",
    "population": "VI"
  }
}
View verified result
Shortened result
{
  "var_id": "vg0100001306",
  "frequency": {
    "population": "VI",
    "major_genotype": "G",
    "minor_genotype": "A",
    "major_rate": 1.0,
    "minor_rate": 0.0,
    "count": 96
  }
}

Source · RiceVarMap REST response

Page through a gene and follow a variant

Use the returned variant ID for the follow-up. Keep the original gene query and advance its offset for the next page.

List the first five variants in LOC_Os05g32860 with no flanks. Check the second variant in IndII and VI, then show the next page.

Show the first five variants in the gene body.

list_gene_variants
{
  "name": "list_gene_variants",
  "arguments": {
    "gene_id": "LOC_Os05g32860",
    "population": "All",
    "up": 0,
    "down": 0,
    "limit": 5,
    "offset": 0
  }
}
View verified result
Shortened result
{
  "gene_id": "LOC_Os05g32860",
  "reference": "NIP",
  "query_interval": {
    "chr": "chr05",
    "start": 19240767,
    "end": 19241433,
    "up": 0,
    "down": 0
  },
  "population": "All",
  "count": 8,
  "limit": 5,
  "offset": 0,
  "variants": [
    {
      "var_id": "vg0519240824",
      "pos": 19240824,
      "type": "SNP",
      "ref": "C",
      "alt": "T",
      "minor_rate": 0.001,
      "count": 4726
    },
    {
      "var_id": "vg0519240874",
      "pos": 19240874,
      "type": "INDEL",
      "ref": "C",
      "alt": "CA",
      "minor_rate": 0.037,
      "count": 4726
    },
    {
      "var_id": "vg0519240886",
      "pos": 19240886,
      "type": "SNP",
      "ref": "C",
      "alt": "T",
      "minor_rate": 0.002,
      "count": 4726
    },
    {
      "var_id": "vg0519240901",
      "pos": 19240901,
      "type": "INDEL",
      "ref": "ATAGT",
      "alt": "A",
      "minor_rate": 0.102,
      "count": 4726
    },
    {
      "var_id": "vg0519241183",
      "pos": 19241183,
      "type": "SNP",
      "ref": "G",
      "alt": "C",
      "minor_rate": 0.038,
      "count": 4726
    }
  ]
}

Source · RiceVarMap REST response

Check the second variant, vg0519240874, in IndII.

get_variant_frequency
{
  "name": "get_variant_frequency",
  "arguments": {
    "var_id": "vg0519240874",
    "population": "IndII"
  }
}
View verified result
Shortened result
{
  "var_id": "vg0519240874",
  "frequency": {
    "population": "IndII",
    "major_genotype": "C",
    "minor_genotype": "CA",
    "major_rate": 1.0,
    "minor_rate": 0.0,
    "count": 465
  }
}

Source · RiceVarMap REST response

Check the second variant, vg0519240874, in VI.

get_variant_frequency
{
  "name": "get_variant_frequency",
  "arguments": {
    "var_id": "vg0519240874",
    "population": "VI"
  }
}
View verified result
Shortened result
{
  "var_id": "vg0519240874",
  "frequency": {
    "population": "VI",
    "major_genotype": "C",
    "minor_genotype": "CA",
    "major_rate": 1.0,
    "minor_rate": 0.0,
    "count": 96
  }
}

Source · RiceVarMap REST response

Show the next page for the same gene and population.

list_gene_variants
{
  "name": "list_gene_variants",
  "arguments": {
    "gene_id": "LOC_Os05g32860",
    "population": "All",
    "up": 0,
    "down": 0,
    "limit": 5,
    "offset": 5
  }
}
View verified result
Shortened result
{
  "gene_id": "LOC_Os05g32860",
  "reference": "NIP",
  "query_interval": {
    "chr": "chr05",
    "start": 19240767,
    "end": 19241433,
    "up": 0,
    "down": 0
  },
  "population": "All",
  "count": 8,
  "limit": 5,
  "offset": 5,
  "variants": [
    {
      "var_id": "vg0519241199",
      "pos": 19241199,
      "type": "SNP",
      "ref": "G",
      "alt": "T",
      "minor_rate": 0.216,
      "count": 4726
    },
    {
      "var_id": "vg0519241330",
      "pos": 19241330,
      "type": "SNP",
      "ref": "G",
      "alt": "A",
      "minor_rate": 0.466,
      "count": 4726
    },
    {
      "var_id": "vg0519241389",
      "pos": 19241389,
      "type": "SNP",
      "ref": "G",
      "alt": "A",
      "minor_rate": 0.467,
      "count": 4726
    }
  ]
}

Source · RiceVarMap REST response

Read raw and imputed genotypes

Use exact cultivar IDs. The genotype tool returns raw and imputed calls as separate fields.

Give me the raw and imputed genotype for B001 at vg0722097923, then compare two cultivars across three sites.

Show both genotype fields for B001 at vg0722097923.

query_genotypes
{
  "name": "query_genotypes",
  "arguments": {
    "var_ids": [
      "vg0722097923"
    ],
    "cultivars": [
      "B001"
    ]
  }
}
View verified result
Shortened result
{
  "results": [
    {
      "var_id": "vg0722097923",
      "genotypes": {
        "B001": {
          "imputed": "G",
          "raw": "G"
        }
      }
    }
  ],
  "not_found": []
}

Source · POST https://ricevarmap.ncpgr.cn/v3/api/genotypes/query · Request format

Show both genotype fields for B001 and C001 at all three sites.

query_genotypes
{
  "name": "query_genotypes",
  "arguments": {
    "var_ids": [
      "vg0722097923",
      "vg0100001306",
      "vg0519240901"
    ],
    "cultivars": [
      "B001",
      "C001"
    ]
  }
}
View verified result
Shortened result
{
  "results": [
    {
      "var_id": "vg0722097923",
      "genotypes": {
        "B001": {
          "imputed": "G",
          "raw": "G"
        },
        "C001": {
          "imputed": "G",
          "raw": "G"
        }
      }
    },
    {
      "var_id": "vg0100001306",
      "genotypes": {
        "B001": {
          "imputed": "G",
          "raw": "G"
        },
        "C001": {
          "imputed": "G",
          "raw": "G"
        }
      }
    },
    {
      "var_id": "vg0519240901",
      "genotypes": {
        "B001": {
          "imputed": "ATAGT",
          "raw": "ATAGT"
        },
        "C001": {
          "imputed": "A",
          "raw": "N"
        }
      }
    }
  ],
  "not_found": []
}

Source · POST https://ricevarmap.ncpgr.cn/v3/api/genotypes/query · Request format

Reading results

Keep the returned variant ID when asking about another population. Each tool call takes explicit IDs and population codes.

Gene windows use upstream and downstream distances in bp. List positions refer to the returned page. Use the returned ID when selecting a variant.

Preserve 0 and null separately. Raw and Imputed are returned as separate genotype fields. Coordinate mappings retain their source and target references.

TOC

Navigation